Leveraging facets, sorting, and pagination (Shopify Hydrogen)

This is for:

Developer

In this article

Define and access target controller hooks
Facets
Sorting
Pagination

Facets, sorting, and pagination are essential components of any commerce interface. These features improve the user experience by helping users find what they need when browsing product lists.

Note

In the following sections, you’ll notice that Headless doesn’t specify details about what should be returned by the Commerce API, such as which facets are available, the types of sorting criteria, and how many items are displayed per page. Because of the declarative nature of the Commerce API, this information is determined by the configuration associated with the Commerce API request.

Define and access target controller hooks

Common functionalities, such as pagination, facets, and sorting, rely on target controller hooks. Define and retrieve them as follows:

// lib/commerce-engine-config.ts

import {
  definePagination,
  defineFacetGenerator,
  defineSort,
  // ...
} from '@coveo/headless-react/ssr-commerce';

export default {
  // ...
  controllers: {
    pagination: definePagination({options: {pageSize: 9}}), 
    facetGenerator: defineFacetGenerator(),
    sort: defineSort(),
    // ...
  },
} satisfies CommerceEngineDefinitionOptions;

Define the pagination controller with the target default page size.

Facets let users filter search results by specific attributes, making it easier to find relevant items.

Use a FacetGenerator controller hook to access a list of facets that can be rendered in the UI. See About the Facet Generator.

There are five types of facets:

Regular
Numerical range
Category
Date range
Location

The following code snippet shows how to render facets using the FacetGenerator based on their type.

import type {
  MappedFacetState,
  RegularFacet,
  RegularFacetState,
  NumericFacetState,
  NumericFacet,
  RegularFacetValue,
  CategoryFacetState,
  CategoryFacet,
} from '@coveo/headless/ssr-commerce';

import {engineDefinition} from '~/lib/coveo.engine';

type FacetGenerator = ReturnType<
  typeof engineDefinition.controllers.useFacetGenerator
>;

export function Facets() {
  const facetGenerator = engineDefinition.controllers.useFacetGenerator(); 

  return (
    <div>
      {facetGenerator.state.map((facet) => { 
        switch (facet.type) {
          case 'regular':
            return (
              <RegularFacetContent 
                key={facet.facetId}
                staticState={facet}
                facetController={facetGenerator.methods?.getFacetController(
                  facet.facetId,
                  'regular',
                )}
              />
            );
          case 'numericalRange':
            return (
              <NumericFacetContent
                key={facet.facetId}
                staticState={facet}
                facetController={facetGenerator.methods?.getFacetController(
                  facet.facetId,
                  'numericalRange',
                )}
              />
            );
          case 'hierarchical':
            return (
              <CategoryFacetContent
                key={facet.facetId}
                staticState={facet}
                facetController={facetGenerator.methods?.getFacetController(
                  facet.facetId,
                  'hierarchical',
                )}
              />
            );
          default:
            return null;
        }
      })}
    </div>
  );
}

function RegularFacetContent({
  staticState,
  facetController,
}: {
  staticState: RegularFacetState;
  facetController?: RegularFacet;
}) {
  return (
    <>
      {staticState.values.map((facetValue) => ( 
        <div key={facetValue.value}>
          <input
            type="checkbox"
            defaultChecked={facetValue.state === 'selected'}
            onChange={() => facetController?.toggleSelect(facetValue)}
          />
          <label>
            {facetValue.value} ({facetValue.numberOfResults})
          </label>
        </div>
      ))}
    </>
  );
}

	Retrieve your `facetGenerator` controller hook.
	Iterate over the facets returned by the controller. Render a different component based on the facet’s type.
	Render the `RegularFacetContent` component for regular facets, passing in the facet and the facet controller.
	Render the facet values as checkboxes. When the user selects a checkbox, call the `toggleSelect` method to select or deselect the facet value.

Note

For details on implementing other types of facets, see the Barca Sports Hydrogen sample repository.

Sorting

Sorting lets users order results based on certain criteria like relevance, popularity, or price.

The following snippet shows how to implement sorting:

import {engineDefinition} from '~/lib/coveo.engine';
import type {SortCriterion} from '@coveo/headless-react/ssr-commerce';
import {SortBy} from '@coveo/headless-react/ssr-commerce';

export function Sorts() {
  const sort = engineDefinition.controllers.useSort(); 

  const handleSortSelection = (option: SortCriterion) => {
    sort.methods?.sortBy(option);
  };

  const getSortLabel = (option: SortCriterion) =>
    option.by === SortBy.Fields ? option.fields[0].displayName : option.by;

  return (
    <>
      {sort.state.availableSorts.map((option) => ( 
        <button
          key={getSortLabel(option)}
          onClick={() => handleSortSelection(option)} 
        >
          {getSortLabel(option)} 
        </button>
      ))}
    </>
  );
}

	Retrieve your `sort` controller hook.
	Display buttons for each available option.
	When a user selects a button, call the `handleSortSelection` helper method. This method uses the `sortBy` method to sort results based on the selected option.
	Display the option label.

Metadata keys defined in variant and availability data can be used for filtering with facets, but can’t be used for sorting results.

Pagination

Pagination breaks large sets of results into smaller, manageable pages, improving navigation.

The following snippet shows how to implement pagination in a Shopify Hydrogen interface:

import {engineDefinition} from '~/lib/coveo.engine';

export function Pagination() {
  const pagination = engineDefinition.controllers.usePagination(); 

  return (
    pagination.state.totalPages > 1 && (
      <div> 
        <button onClick={() => pagination.methods?.previousPage()}>
          Previous
        </button>
        <br></br>
        <button onClick={() => pagination.methods?.nextPage()}>
          Next
        </button>
      </div>
    )
  );
}

	Retrieve your `pagination` controller hook.
	Display buttons to navigate between pages.

Was this article useful?

Very useful

Not really