React InstantSearch widget that filters the dataset based on color facet values. Equivalent of the official RefinementList widget but displaying a color indicator instead of text facet values.

Compatible with React InstantSearch v7. For v6 compatibility, please use version 1.4.7.

This helps the user quickly visualize the kind of color that you have in your index. This is a great widget to refine records within multiple shades of a single color (like choosing the color of a jean for example).

---

Summary

• Demo
• Installation
• Migration from v1
• Usage
• Styling
  • CSS variables
• Requirements
• Options
• Example
• Testing
• Browser Support
• Troubleshooting
• Contributing & License

Get started

Demo

Demo on CodeSandbox.

Installation

For React InstantSearch v7 (Current)

npm install @algolia/react-instantsearch-widget-color-refinement-list react-instantsearch
# or
yarn add @algolia/react-instantsearch-widget-color-refinement-list react-instantsearch

For React InstantSearch v6 (Legacy)

If you're still using React InstantSearch v6, install version 1.4.7:

npm install @algolia/[email protected] react-instantsearch-dom
# or
yarn add @algolia/[email protected] react-instantsearch-dom

Migration from v1

Upgrading from v1.x (React InstantSearch v6) to v2.x (React InstantSearch v7)?

📖 See the complete Migration Guide (v1 → v2) for detailed step-by-step instructions, code examples, and troubleshooting tips.

Quick Summary:

• Update dependencies: react-instantsearch-dom → react-instantsearch
• Update imports and search client initialisation
• Widget API remains unchanged ✅

For additional context, refer to the React InstantSearch v7 migration guide.

Usage

import React from 'react';
import { createRoot } from 'react-dom/client';
import { InstantSearch, SearchBox, Hits } from 'react-instantsearch';
import algoliasearch from 'algoliasearch/lite';
import {
  ColorRefinementList,
  Layout,
  Shape,
} from '@algolia/react-instantsearch-widget-color-refinement-list';

// Import default styles
import '@algolia/react-instantsearch-widget-color-refinement-list/dist/style.css';

const searchClient = algoliasearch('appId', 'apiKey');

const App = () => (
  <InstantSearch indexName="indexName" searchClient={searchClient}>
    <SearchBox />
    <ColorRefinementList
      attribute="color"
      separator=";"
      layout={Layout.Grid}
      shape={Shape.Circle}
    />
    <Hits />
  </InstantSearch>
);

createRoot(document.getElementById('root')!).render(<App />);

Styling

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

import '@algolia/react-instantsearch-widget-color-refinement-list/dist/style.css';

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@algolia/react-instantsearch-widget-color-refinement-list/dist/style.css"
/>

CSS variables

The widget styles uses CSS variables that you can customize in your own CSS.
You can override CSS variables using 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.

Requirements

• In your records, color attributes should have a title and hexadecimal code separated by a semicolon ; (by default, but it can be customized using the separator option) for the widget to work.
• You can also use an URL instead of the hexadecimal code if you want to display a pattern for example.
• The color attribute should be added to attributesForFaceting in your configuration.

Color facet value examples:

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

Note: The hexadecimal code length can be 3 or 6 chars (excluding the # symbol).

Sample record example:

{
  "objectID": 0,
  "color": "black;#000"
}

Options

Option	Type	Required	Default	Description
attribute	string	true	-	Name of the attribute that contains the color in the record.
sortByColor	boolean	false	true	Sort facet values by color distance.
layout	enum:Grid|List	false	Grid	UI layout of the facet values.
shape	enum:Circle|Square	false	Circle	UI color shape.
pinRefined	boolean	false	false	When displaying the showMore button and the list is not expanded, should the refined items be pinned to the top or remain in the same order.
limit	number	false	10	How many facet values to retrieve.
showMore	boolean	false	false	Whether to display a button that expands the number of items.
showMoreLimit	number	false	20	Maximum number of displayed items. Only used when showMore is set to true.
separator	string	false	;	Color facet value separator.
className	string	false	-	Custom CSS classes.
translations	object	false	-	A mapping of keys to translation values.
transformItems	function	false	undefined	Modifies the items being displayed, for example, to filter or sort them. It takes items as argument and expects them back in return.

attribute

string | required

Name of the attribute that contains the color in the record.

<ColorRefinementList attribute="color" />

sortByColor

boolean

Sort facet values by color distance.

<ColorRefinementList sortByColor={true} />

layout

enum:'Grid'|'List'

UI layout of the facet values.

import {
  ColorRefinementList,
  Layout,
} from '@algolia/react-instantsearch-widget-color-refinement-list';

<ColorRefinementList layout={Layout.Grid} />;

shape

enum:'Circle'|'Square'

UI color shape.

import {
  ColorRefinementList,
  Shape,
} from '@algolia/react-instantsearch-widget-color-refinement-list';

<ColorRefinementList shape={Shape.Circle} />;

pinRefined

boolean

When displaying the showMore button and the list is not expanded, should the refined items be pinned to the top or remain in the same order.

<ColorRefinementList limit={5} showMore={true} pinRefined={true} />;

limit

number

How many facet values to retrieve.

<ColorRefinementList limit={10} />

showMore

boolean

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

<ColorRefinementList showMore={true} />

showMoreLimit

number

Maximum number of displayed items. Only used when showMore is set to true.

<ColorRefinementList showMoreLimit={20} />

separator

string

Color facet value separator.

<ColorRefinementList separator="//" />

className

string

Custom CSS classes.

<ColorRefinementList className="my-class" />

translations

object

A mapping of keys to translation values.

• refineOn: aria-label value for an item. Accepts one string parameter that is the current item value.
• colors: 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.

<LoadMoreWithProgressBar
  translations={{
    refineOn: (value: string) => `Refine on ${value}`,
    colors: (refinedCount: number) =>
      `Colors${refinedCount ? `, ${refinedCount} selected` : ''}`,
    showMore: (expanded: boolean) =>
      expanded ? 'Show less' : 'Show more',
  }}
/>

transformItems

function

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

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

Example

Clone this repository and go to the repo folder:

git clone [email protected]:algolia/react-instantsearch-widget-color-refinement-list.git && \
cd react-instantsearch-widget-color-refinement-list

Install the dependencies and start the example:

npm install && npm start
# or
yarn install && yarn start

Then open http://localhost:3000/ to see the example in action.

Testing

This widget includes a comprehensive test suite to ensure reliability and compatibility with React InstantSearch v7.

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage report
npm test -- --coverage

# Type checking
npm run test:types

Test Coverage

The test suite includes:

• Unit tests - Utility functions, colour parsing, and sorting algorithms
• Component tests - UI rendering, interactions, and accessibility
• Widget integration tests - InstantSearch integration and refinement logic
• E2E tests - Real Algolia backend integration tests

Coverage: ~85% code coverage with enforced thresholds (80-85%)

Browser support

This widget follows the same browser support as React InstantSearch v7:

• Last two versions of major browsers: Chrome, Edge, Firefox, Safari
• React: 16.8.0 or higher (Hooks support required)
• Node.js: 14.x or higher (for development)

Please refer to the browser support section in the documentation to use React InstantSearch and this widget on other browsers.

Troubleshooting

Encountering an issue? Before reaching out to support, we recommend heading to our FAQ where you will find answers for the most common issues and gotchas with the library.

Contributing & License

How to contribute

We welcome all contributors, from casual to regular 💙

• Bug report. Is something not working as expected? Send a bug report.
• Feature request. Would you like to add something to the library? Send a feature request.
• Documentation. Did you find a typo in the doc? Open an issue and we'll take care of it.
• Development. If you don't know where to start, you can check the open issues that are tagged easy, the bugs or chores.

To start contributing to code, you need to:

1. Fork the project
2. Clone the repository
3. Install the dependencies: yarn
4. Run the development mode: yarn start
5. Open the project

Please read our contribution process to learn more.

License

Licensed under the MIT license.

---

About React InstantSearch

React InstantSearch is a React library that lets you create an instant-search result experience using Algolia’s search API. It is part of the InstantSearch family:

React InstantSearch | InstantSearch.js | Angular InstantSearch | Vue InstantSearch | InstantSearch Android | InstantSearch iOS

This project was generated with create-instantsearch-app by Algolia.