Filters

Introduction

Our filters feature allows you to fetch a product list based on selected options like color or size. These options are based on the product attributes added to the products on the page for each category.

Retrieving filters

To retrieve filters, you can use the getFilters SDK method.

The getFilters SDK method will fetch filters from BigCommerce GraphQL API and return the raw response. The response from the GraphQL API is a little bit different than the response from BigCommerce REST API. For example, your response might look like this:

{
  "edges": [
    {
      "node": {
        "name": "Color",
        "__typename": "ProductAttributeSearchFilter",
        "attributes": {
          "edges": [
            {
              "node": {
                "value": "Black",
                "productCount": 1,
                "isSelected": false
              }
            },
            {
              "node": {
                "value": "Blue",
                "productCount": 1,
                "isSelected": false
              }
            },
            {
              "node": {
                "value": "Orange",
                "productCount": 1,
                "isSelected": false
              }
            },
            {
              "node": {
                "value": "Silver",
                "productCount": 1,
                "isSelected": false
              }
            }
          ]
        },
        "isCollapsedByDefault": false
      }
    },
    {
      "node": {
        "name": "Size",
        "__typename": "ProductAttributeSearchFilter",
        "attributes": {
          "edges": [
            {
              "node": {
                "value": "Large",
                "productCount": 1,
                "isSelected": false
              }
            },
            {
              "node": {
                "value": "Medium",
                "productCount": 1,
                "isSelected": false
              }
            },
            {
              "node": {
                "value": "Small",
                "productCount": 1,
                "isSelected": false
              }
            }
          ]
        },
        "isCollapsedByDefault": false
      }
    }
  ]
}

So to get the filter values, it's necessary to do some mapping to get each node. Based on this response, you can start building your UI for filters selection. Example implementation of fetching the filters might look like this:

import { sdk } from '~/sdk.config.ts';

setup() {
  const currentCategoryId = 1;
  const filters = ref([]);

  async function fetchAvailableFilters() {
    const rawFilters = await sdk.bigcommerce.getFilters({
      filters: {
        categoryEntityId: currentCategoryId
      }
    });

    return raw.edges.map((item) => item.node);
  }

  onMounted(() => {
    filters.value = fetchAvailableFilters()
  });

  return filters;
}

Filtering products

Filtering products by attributes is only available via the of BigCommerce GraphQL API. To filter products, you can use the getProductsWithFilter method.

To make this call properly, it's necessary to properly format the filter parameters.

For example, let's say we want to filter products in our current category to only get products where the Color attribute equals Red.

const exampleFilters = {
  categoryEntityId: currentCategoryId,
  productAttributes: [
    {
      attribute: 'Color',
      values: ['Red']
    }
  ]
};

The attribute parameter should match as name parameter of the filter response from Retrieving filters section. The values parameter contains the array of attribute value parameters in the same response.

If you want to filter by more attributes, you can add more attribute/values to the productAttributes array.

const exampleFilters = {
  categoryEntityId: currentCategoryId,
  productAttributes: [
    {
      attribute: 'Color',
      values: ['Red', 'Blue']
    },
    {
      attribute: 'Size',
      values: ['Large']
    }
  ]
};

Example implementation of filtering products might look like this:

import { sdk } from '~/sdk.config.ts';

setup() {
  const products = ref([]);
  const pageInfo = ref({});
  const sort = 'FEATURED';
  const itemsPerPage = 10;

  useFetch(async () => {
    const filters = {
      categoryEntityId: currentCategoryId,
      productAttributes: [
        {
          attribute: 'Color',
          values: ['Red', 'Blue']
        },
        {
          attribute: 'Size',
          values: ['Large']
        }
      ]
    }

    const res = await sdk.bigcommerce.getProductsWithFilter({
      filters,
      first: itemsPerPage,
      sort
    });

    products.value = res.data
    pageInfo.value = res.meta
  });
}

Sorting

To use useProduct().filter method with sorting, it's necessary to make some changes with Sort by logic. BigCommerce GraphQL API requires other sorting values than REST API.

In Nuxt2 storefronts, sorting values are added to themeConfig.js file.

Below you can find configuration proper for GraphQL API and sorting:

productsSortOptions: [
    { label: 'Featured', id: 1, value: { sort: 'FEATURED' } },
    { label: 'Relevance', id: 2, value: { sort: 'RELEVANCE' } },
    { label: 'Best selling', id: 3, value: { sort: 'BEST_SELLING' } },
    { label: 'Best reviewed', id: 4, value: { sort: 'BEST_REVIEWED' } },
    { label: 'Newest', id: 5, value: { sort: 'NEWEST' } },
    { label: 'Name: A to Z', id: 6, value: { sort: 'A_TO_Z' } },
    { label: 'Name: Z to A', id: 7, value: { sort: 'Z_TO_A' } },
    {
      label: 'Price from high to low',
      id: 8,
      value: { sort: 'HIGHEST_PRICE' }
    },
    { label: 'Price from low to high', id: 9, value: { sort: 'LOWEST_PRICE' } }
  ],

sort params like FEATURED or A_TO_Z should be added as sort param to useProduct().filter method:

const res = await sdk.bigcommerce.getProductsWithFilter({
  filters,
  first: 10,
  sort: 'FEATURED'
});

Pagination

Default pagination does not exist in the BigCommerce integration so there is no way to create page functionality. However, there is a way to create Show more logic on your website.

The idea is to fetch first part of the product at start, and add every new fetched product to the list of products instead of replacing it. First fetch might load 10 products, next fetch would add new 10 products to the list of products - now 20 products would be visible on the page.

To understand how to build such a feature, first you should focus on the response of getProductsWithFilter method.

Example response might look like this:

{
  "data": [
    // List of products
  ],
  "meta": {
    "totalItems": 5,
    "pageInfo": {
      "hasNextPage": true,
      "hasPreviousPage": false,
      "startCursor": "WzEwMDAwMDAwMCwwLDkzXQ==",
      "endCursor": "WzEwMDAwMDAwMCwwLDg4XQ=="
    }
  }
}

Information to build "show more" functionality is included in meta.pageInfo param.

hasNextPage defines if there are more products to fetch
endCursor is the unique value for each product that can be used to define after which product we want to start fetching more products

Then, we can use the filter method and specify the after parameter, where endCursor should be used:

setup() {
  const products = ref([]);
  const pageInfo = ref({});
  const sort = 'FEATURED';
  const itemsPerPage = 10;

  useFetch(async () => {
    const filters = {
      categoryEntityId: currentCategoryId,
      productAttributes: [
        {
          attribute: 'Color',
          values: ['Red', 'Blue']
        },
        {
          attribute: 'Size',
          values: ['Large']
        }
      ]
    }

    const res = await sdk.bigcommerce.getProductsWithFilter({
      filters,
      first: itemsPerPage,
      after: pageInfo.value.endCursor
      sort
    });

    products.value = res.data
    pageInfo.value = res.meta
  });
}

Now, the itemsPerPage number of products will start fetching products after last where the previous fetch left off.

To fetch more products, you need to trigger the getProductsWithFilter methods with the after parameter.

Limitations

Maximum 50 products can be fetched during 1 fetch - limitation of BigCommerce GraphQL API.