Refinements

A refinement acts as a search filter on the search UI's left panel. The order of each refinement follows the declaration order in the configuration file.

refinements

object[]

Each refinement object contains the following properties:

Key	Type	Description	Preview
type	"list" | "category" | "hierarchical" | "slider"	The type of the refinement.	N/A
header	string	The content to display in the refinement panel header.
label	string	The label to display in the active refinements.
options	object	The refinement options forwarded to the underlying InstantSearch widget.	N/A

You need to add the attributes that you provide to the refinements' options as attributes for faceting, either on the Algolia dashboard or using attributesForFaceting with the Algolia API.

Example:

export const refinements = [
  {
    type: 'list',
    header: 'Brands',
    label: 'Brand',
    options: {
      attribute: 'brand',
    },
  },
  // ...
];

Types

"hierarchical"

Preview
	The hierarchical refinement creates a navigation based on a hierarchy of facet attributes. It is commonly used for categories with subcategories.

Record schema

The records to use in the hierarchical menu must follow this structure:

[
  {
    "objectID": "321432",
    "name": "lemon",
    "categories.lvl0": "products",
    "categories.lvl1": "products > fruits"
  },
  {
    "objectID": "8976987",
    "name": "orange",
    "categories.lvl0": "products",
    "categories.lvl1": "products > fruits"
  }
]

You can also provide more than one path for each level:

[
  {
    "objectID": "321432",
    "name": "lemon",
    "categories.lvl0": ["products", "goods"],
    "categories.lvl1": ["products > fruits", "goods > to eat"]
  }
]

Options

Key	Type	Description
type	"hierarchical"	The type of the refinement.
header	string	The content to display in the refinement panel header.
label	string	The label to display in the active refinements.
options	object	The options forwarded to the HierarchicalMenu InstantSearch widget.

Example:

export const refinements = [
  {
    type: 'hierarchical',
    header: 'Categories',
    label: 'Category',
    options: {
      attributes: [
        'hierarchicalCategories.lvl0',
        'hierarchicalCategories.lvl1',
      ],
      limit: 6,
      showMore: true,
    },
  },
  // ...
];

"category"

Preview
	The category refinement displays a menu that lets the user choose a single value for a specific attribute.

Options

Key	Type	Description
type	"category"	The type of the refinement.
header	string	The content to display in the refinement panel header.
label	string	The label to display in the active refinements.
options	object	The options forwarded to the Menu InstantSearch widget.

Example:

export const refinements = [
  {
    type: 'category',
    header: 'Categories',
    label: 'Category',
    options: {
      attribute: 'category',
      limit: 6,
      showMore: true,
    },
  },
  // ...
];

"list"

Preview
	The list refinement displays a list that lets the user choose multiple values for a specific attribute.

Options

Key	Type	Description
type	"list"	The type of the refinement.
header	string	The content to display in the refinement panel header.
label	string	The label to display in the active refinements.
options	object	The options forwarded to the RefinementList InstantSearch widget.

Example:

export const refinements = [
  {
    type: 'list',
    header: 'Brands',
    label: 'Brand',
    options: {
      attribute: 'brand',
      searchable: true,
      showMore: true,
      limit: 6,
    },
  },
  // ...
];

"slider"

Preview
	The slider refinement provides a user-friendly way to filter the results based on a single numeric range.

Record schema

The values inside attribute must be numbers, not strings.

Options

Key	Type	Description
type	"slider"	The type of the refinement.
header	string	The content to display in the refinement panel header.
label	string	The label to display in the active refinements.
options	RefinementOptions	The options of the refinement.

RefinementOptions

Name	Type	Description
transformValue	(value: number) => ReactNode	A function to transform the minimum and maximum displayed values.

Example:

export const refinements = [
  {
    type: 'slider',
    header: 'Price',
    label: 'Price',
    options: {
      attribute: 'price',
      transformValue: (value) => (
        <>
          <span className="uni-Hit-currency">$</span>
          {value}
        </>
      ),
    },
  },
  // ...
];