Customizing the search UI

The configuration file lets you customize the search UI: what refinements to display, what sorting strategy to use, etc.

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.

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 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:

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

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:

const config = {
  // ...
  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:

const config = {
  // ...
  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:

const config = {
  // ...
  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	Function to transform the minimum and maximum displayed values.

Example:

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

Sorting

The sorts configuration displays a list of indices, allowing a user to change the way hits are sorted (with replica indices).

You must define all indices that you pass as replicas of the main index.

Key	Type	Description
label	string	The label to display for the index.
value	string	The Algolia index name to target.

Example:

const config = {
  // ...
  sorts: [
    {
      label: 'Featured',
      value: 'instant_search',
    },
    {
      label: 'Price ascending',
      value: 'instant_search_price_asc',
    },
    {
      label: 'Price descending',
      value: 'instant_search_price_desc',
    },
  ],
};