ColorRefinementList | React InstantSearch V6 (Deprecated)

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.

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

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

1
<ColorRefinementList attribute="color" />

sortByColor

Sort facet values by color distance.

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

layout

UI layout of the facet values.

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

shape

UI color shape.

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

pinRefined

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

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

limit

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

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

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

showMoreLimit

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

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

separator

Color facet value separator.

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

transformItems

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

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';
    },
  }}
/>