Handling Facets

Overview

Facets are a great way to allow users to filter products. In this guide, we will explore how to build a facet experience using the Merchstack API.

Before we get started, we are assuming that you have already set up your project to access the Merchstack API. If you have not, please refer to the Accessing the API section of the documentation.

Handling Facets

In an ecommerce store, facets are used to allow users to filter a list of products. For example, a user may want to filter a list of products by size, color, or price.

The Merchstack API provides you the facets with the alternativeSearch query that can be used to retrieve a list of facets for a given search query. This query can be used to build a facet experience.

Facets are returned as an array of objects. Each object contains the following properties:

• name - The name of the facet
• rank - The rank of the facet
• values - An array of facet values

Each facet value contains the following properties:

• name - The name of the facet value
• slug - The slug of the facet value
• count - The number of products that match the facet value

The following example demonstrates how to retrieve a list of facets for a given search query:

import React from 'react'
import { useQuery, gql } from '@apollo/client'

const GET_FACETS = gql`
  query GetFacets($query: String!) {
    alternativeSearch(query: $query) {
      facets {
        name
        rank
        values {
          name
          slug
          count
        }
      }
    }
  }
`

const Facets = ({ query }) => {
  const { loading, error, data } = useQuery(GET_FACETS, {
    variables: { 
      inStock: true,
      term: query,
    },
  })

  if (loading) return <p>Loading...</p>
  if (error) return <p>Error :(</p>

  return (
    <ul>
      {data.alternativeSearch.facets.map((facet) => (
        <li key={facet.name}>
          <h3>{facet.name}</h3>

          <ul>
            {facet.values.map((value) => (
              <li key={value.slug}>
                <a href={`?query=${query}&facets=${value.slug}`}>
                  {value.name} ({value.count})
                </a>
              </li>
            ))}
          </ul>
        </li>
      ))}
    </ul>
  )
}

export default Facets

In the example above, we are using the alternativeSearch query to retrieve a list of facets. We are also using the inStock variable to only return facets for products that are in stock. This is a great way to ensure that the facets are relevant to the user.

Next, we will use the facets as a way to filter the list of products. The alternativeSearch query allows you to filter products by facets using the facets variable. The facets variable accepts an array of facet filters (name and value). The following example demonstrates how to filter products by facets:

import React from 'react'
import { useQuery, gql } from '@apollo/client'

const GET_PRODUCTS = gql`
  query GetProducts($query: String!, $facets: [String!]) {
    alternativeSearch(query: $query, facets: $facets) {
      products {
        name
        slug
        price
        images {
          url
        }
      }
    }
  }
`

const Products = ({ query }) => {
  const { loading, error, data } = useQuery(GET_PRODUCTS, {
    variables: {
      term: query,
      facets: [{ name: 'size', value: 'small' }]
    },
  })

  if (loading) return <p>Loading...</p>
  if (error) return <p>Error :(</p>

  return (
    <ul>
      {data.alternativeSearch.products.map((product) => (
        <li key={product.slug}>
          <h3>{product.name}</h3>

          <img src={product.images[0].url} alt={product.name} />

          <p>{product.price}</p>
        </li>
      ))}
    </ul>
  )
}

export default Products

More Information on Alternate Search

The alternativeSearch query is a powerful query that allows you to search for products based on a variety of criteria. For more information on the alternativeSearch query or any other queries, please refer to the GraphQL Playground -> Docs -> alternativeSearch

We will keep referring to the alternativeSearch query throughout the storefront integration documentation. It is important to understand how to use this query. We recommend that you spend some time familiarizing yourself with the query.