UI libraries / React InstantSearch / Widgets

ColorRefinementList labs

This widget is an experiment and its API is subject to change without prior notice.

If you experience any issues, send a bug report. You can also contact us if you have any feedback or feature suggestion.

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}
/>
Import
Copy 
1
2
3

import {
  ColorRefinementList
} from '@algolia/react-instantsearch-widget-color-refinement-list';
See code examples
See live example

About this widget

We released React InstantSearch Hooks, a new InstantSearch library for React. We recommend using React InstantSearch Hooks in new projects or upgrading from React InstantSearch.

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.

Copy 
1

import '@algolia/react-instantsearch-widget-color-refinement-list/dist/style.css';
Copy 
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

Copy 
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
type: string
Required

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

<ColorRefinementList attribute="color" />
sortByColor
type: boolean
default: false
Optional

Sort facet values by color distance.
Copy 
1
2
3
4

<ColorRefinementList
  // ...
  sortByColor
/>
layout
type: string ("Grid"|"List")
default: "Grid"
Optional

UI layout of the facet values.
Copy 
1
2
3
4

<ColorRefinementList
  // ...
  layout="List"
/>
shape
type: string ("Circle"|"Square")
default: "Circle"
Optional

UI color shape.
Copy 
1
2
3
4

<ColorRefinementList
  // ...
  shape="Square"
/>
pinRefined
type: boolean
default: false
Optional

Pins refined items to the top when the list is expanded with showMore.
Copy 
1
2
3
4

<ColorRefinementList
  // ...
  pinRefined
/>
limit
type: number
default: 10
Optional

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.
Copy 
1
2
3
4

<ColorRefinementList
  // ...
  limit={20}
/>
showMore
type: boolean
default: false
Optional

Whether to display a button that expands the number of items.
Copy 
1
2
3
4

<ColorRefinementList
  // ...
  showMore
/>
showMoreLimit
type: number
default: 20
Optional

The maximum number of displayed items. Only used when showMore is set to true.
Copy 
1
2
3
4

<ColorRefinementList
  // ...
  showMoreLimit={30}
/>
separator
type: string
default: ";"
Optional

Color facet value separator.
Copy 
1
2
3
4

<ColorRefinementList
  // ...
  separator="//"
/>
transformItems
type: function
Optional

Modifies the items being displayed, for example, to filter or sort them. It takes items as argument and expects them back in return.
Copy 
1
2
3
4
5
6
7
8
9

<ColorRefinementList
  // ...
  transformItems={items =>
    items.map(item => ({
      ...item,
      label: item.label.toUpperCase(),
    }))
  }
/>
translations
type: object
Optional

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.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

<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?
React InstantSearch v6