Algolia DevCon
Oct. 2–3 2024, virtual.
InstantSearch / React / V6 / API reference

ColorRefinementList | React InstantSearch V6 (Deprecated)

Deprecated content
This documentation is for a deprecated version of React InstantSearch. Some features and settings may be missing or their usage may have changed. Refer to the documentation for the latest version of React InstantSearch for up-to-date information.

Signature

Signature
<ColorRefinementList
  attribute={string}
  // Optional parameters
  sortByColor={boolean}
  layout={string}
  shape={string}
  pinRefined={boolean}
  limit={number}
  showMore={boolean}
  showMoreLimit={number}
  separator={string}
  transformItems={function}
  translations={object}
/>

About this widget

The ColorRefinementList widget filters results based on color facet values.

The widget only displays the most relevant colors for the current search context.

Requirements

The attribute provided to the widget must be added in attributes for faceting, either on the dashboard or using attributesForFaceting with the API.

In your records, color attributes should have a title and hexadecimal code separated by a semicolon ; (it can be customized using the separator option). You can also use a URL instead of the hexadecimal code if you want to display a pattern. For example:

  • black;#000
  • red;#f00
  • yellow;#ffff00
  • multicolor;https://example.com/images/rainbow_wheel.png

Styling

The widget ships with default styles that you can import either from the npm package or directly from a CDN like JSDelivr.

1
import '@algolia/react-instantsearch-widget-color-refinement-list/dist/style.css';
1
2
3
4
5
<!-- ... -->
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@algolia/react-instantsearch-widget-color-refinement-list/dist/style.css"
/>

CSS variables

The widget styles use CSS variables that you can customize in your own CSS. You can override CSS variables from the .ais-ColorRefinementList class.

Name Type Description
--transition-duration time Transition duration (used for hover, active, refined states).
--items-column-width length Items grid column width.
--items-gap length Items grid gap.
--refined-icon-size length Refined SVG icon size.
--color-size length Color swatch size.

Examples

1
2
3
4
5
6
import {
  ColorRefinementList
} from '@algolia/react-instantsearch-widget-color-refinement-list';
import '@algolia/react-instantsearch-widget-color-refinement-list/dist/style.css';

<ColorRefinementList attribute="color" />

Props

attribute

Required
Type: string

The name of the attribute that contains the color in the record.

1
<ColorRefinementList attribute="color" />

sortByColor

Optional
Type: boolean

Sort facet values by color distance.

1
2
3
4
<ColorRefinementList
  // ...
  sortByColor
/>

layout

Optional
Type: string ("Grid"|"List")

UI layout of the facet values.

1
2
3
4
<ColorRefinementList
  // ...
  layout="List"
/>

shape

Optional
Type: string ("Circle"|"Square")

UI color shape.

1
2
3
4
<ColorRefinementList
  // ...
  shape="Square"
/>

pinRefined

Optional
Type: boolean

Pins refined items to the top when the list is expanded with #{showMore}.

1
2
3
4
<ColorRefinementList
  // ...
  pinRefined
/>

limit

Optional
Type: number

How many facet values to retrieve. When you enable the #{showMore} feature, this is the number of facet values to display before clicking the “Show more” button.

1
2
3
4
<ColorRefinementList
  // ...
  limit={20}
/>

showMore

Optional
Type: boolean

Whether to display a button that expands the number of items.

1
2
3
4
<ColorRefinementList
  // ...
  showMore
/>

showMoreLimit

Optional
Type: number

The maximum number of displayed items. Only used when #{showMore} is set to true.

1
2
3
4
<ColorRefinementList
  // ...
  showMoreLimit={30}
/>

separator

Optional
Type: string

Color facet value separator.

1
2
3
4
<ColorRefinementList
  // ...
  separator="//"
/>

transformItems

Optional
Type: function

Modifies the items being displayed, for example, to filter or sort them. It takes items as argument and expects them back in return.

1
2
3
4
5
6
7
8
9
<ColorRefinementList
  // ...
  transformItems={items =>
    items.map(item => ({
      ...item,
      label: item.label.toUpperCase(),
    }))
  }
/>

translations

Optional
Type: object

A mapping of keys to translation values.

  • refineOn: the aria-label value for an item. Accepts one string parameter that is the current item value.
  • colors: the aria-label value for items. Accepts one number parameter that is the number of items refined.
  • showMore: the label of the “Show more” button. Accepts one boolean parameter that is true if the values are expanded, false otherwise.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<ColorRefinementList
  // ...
  translations={{
    refineOn(value) {
      return `Refine on ${value}`;
    },
    colors(refinedCount) {
      return `Colors${refinedCount > 0 ? `, ${refinedCount} selected`: ''}`;
    },
    showMore(expanded) {
      return expanded ? 'Show less' : 'Show more';
    },
  }}
/>

Did you find this page helpful?