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.
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
string
The name of the attribute that contains the color in the record.
1
<ColorRefinementList attribute="color" />
sortByColor
boolean
Sort facet values by color distance.
1
2
3
4
<ColorRefinementList
// ...
sortByColor
/>
layout
string ("Grid"|"List")
UI layout of the facet values.
1
2
3
4
<ColorRefinementList
// ...
layout="List"
/>
shape
string ("Circle"|"Square")
UI color shape.
1
2
3
4
<ColorRefinementList
// ...
shape="Square"
/>
pinRefined
boolean
Pins refined items to the top when the list is expanded with #{showMore
}.
1
2
3
4
<ColorRefinementList
// ...
pinRefined
/>
limit
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
boolean
Whether to display a button that expands the number of items.
1
2
3
4
<ColorRefinementList
// ...
showMore
/>
showMoreLimit
number
The maximum number of displayed items. Only used when #{showMore
} is set to true
.
1
2
3
4
<ColorRefinementList
// ...
showMoreLimit={30}
/>
separator
string
Color facet value separator.
1
2
3
4
<ColorRefinementList
// ...
separator="//"
/>
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.
1
2
3
4
5
6
7
8
9
<ColorRefinementList
// ...
transformItems={items =>
items.map(item => ({
...item,
label: item.label.toUpperCase(),
}))
}
/>
translations
object
A mapping of keys to translation values.
refineOn
: thearia-label
value for an item. Accepts onestring
parameter that is the current item value.colors
: thearia-label
value for items. Accepts onenumber
parameter that is the number of items refined.showMore
: the label of the “Show more” button. Accepts one boolean parameter that istrue
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';
},
}}
/>