Filter Button is a component with an inline label and highlighted value. It lets users choose one or more items from an options menu.
Use a Filter Button to offer a list of choices where multiple selection is possible.
Example
function MyFilterButton() {
const items = [
{
label: 'apple',
value: 'apple'
},
{
label: 'banana',
value: 'banana'
},
{
label: 'orange',
value: 'orange'
},
{
label: 'cherry',
value: 'cherry'
},
{
label: 'peach',
value: 'peach'
},
{
label: 'pear',
value: 'pear'
},
{
label: 'grapefruit',
value: 'grapefruit'
},
{
label: 'blackberry',
value: 'blackberry'
},
{
label: 'strawberry',
value: 'strawberry'
},
{
label: 'pineapple',
value: 'pineapple'
}
];
const [selectedItems, setSelectedItems] = useState(items);
return (
<FilterButton
name="Fruits"
items={items}
selectedItems={selectedItems}
onApply={setSelectedItems}
showResetButton
/>
);
}
Variants
Anchor Size
The anchor is available in two sizes: small and medium can be accessed using size prop.
function MyFilterButton() {
const items = [
{
label: 'apple',
value: 'apple'
},
{
label: 'banana',
value: 'banana'
}
];
const initialSelectedItems = [
{
label: 'apple',
value: 'apple'
}
];
const [selectedItems, setSelectedItems] = useState(initialSelectedItems);
return (
<div style={{ display: 'flex', gap: Spacing10 }}>
<FilterButton
name="Fruits"
items={items}
selectedItems={selectedItems}
onApply={setSelectedItems}
size="small"
/>
<FilterButton
name="Fruits"
items={items}
selectedItems={selectedItems}
onApply={setSelectedItems}
size="medium"
/>
</div>
);
}
Custom Sorting
You can use sortPredicate property to have custom sorting on the results when typing your query.
In this example when searching for 'us' or 'ru', unlike the default sorting, 'United States (US)' or 'Russia (RU)' will appear first, respectively.
function MyFilterButton() {
const items = [
{
label: 'Cyprus (CY)',
value: 'cyprus'
},
{
label: 'United States (US)',
value: 'united_states'
},
{
label: 'United Kingdom (UK)',
value: 'united_kingdom'
},
{
label: 'Belgium (BE)',
value: 'belgium'
},
{
label: 'Germany (DE)',
value: 'germany'
},
{
label: 'Russia (RU)',
value: 'russia'
},
{
label: 'Belarus (BY)',
value: 'belarus'
},
{
label: 'Italy (IT)',
value: 'italy'
},
{
label: 'China (CN)',
value: 'china'
},
{
label: 'France (FR)',
value: 'france'
}
];
const [selectedItems, setSelectedItems] = useState([]);
return (
<FilterButton
showResetButton
name="Countries"
items={items}
sortPredicate={(a, b, searchValue) => {
const abbrRegex = new RegExp(`\\b${searchValue}\\b`, 'gi');
return (
Number(abbrRegex.test(b.label)) - Number(abbrRegex.test(a.label))
);
}}
selectedItems={selectedItems}
onApply={setSelectedItems}
/>
);
}
Custom Controls
You have Search input and SelectAll checkbox shown by default, which can be hidden using showSearch and showSelectAll props.
function MyFilterButton() {
const items = [
{
label: 'apple',
value: 'apple'
},
{
label: 'banana',
value: 'banana'
},
{
label: 'orange',
value: 'orange'
},
{
label: 'cherry',
value: 'cherry'
},
{
label: 'peach',
value: 'peach'
},
{
label: 'pear',
value: 'pear'
}
];
const [selectedItems, setSelectedItems] = useState(items);
return (
<FilterButton
name="Fruits"
items={items}
selectedItems={selectedItems}
onApply={setSelectedItems}
showResetButton
showSearch={false}
showSelectAll={false}
/>
);
}
Default Items
You can provide default items which will be used to populate filter once user clicks reset.
If not specified filter with multiple selection will reset all items and with single selction filter will reset to initially selected item
function MyFilterButton() {
const items = [
{
label: 'apple',
value: 'apple'
},
{
label: 'banana',
value: 'banana'
},
{
label: 'kiwi',
value: 'kiwi'
},
{
label: 'pear',
value: 'pear'
},
{
label: 'dragon fruit',
value: 'dragon fruit'
},
{
label: 'plum',
value: 'plum'
},
{
label: 'tangerine',
value: 'tangerine'
},
{
label: 'durian',
value: 'durian'
},
{
label: 'peach',
value: 'peach'
},
{
label: 'mango',
value: 'mango'
}
];
const initialSelectedItems = [
{
label: 'apple',
value: 'apple'
}
];
const defaultItems = [
{
label: 'mango',
value: 'mango'
}
];
const [multipleSelectedItems, setMultipleSelectedItems] =
useState(initialSelectedItems);
const [singleSelectedItems, setSingleSelectedItems] =
useState(initialSelectedItems);
return (
<div style={{ display: 'flex', gap: Spacing10 }}>
<FilterButton
showResetButton
name="Multiple fruits"
items={items}
defaultItems={defaultItems}
selectedItems={multipleSelectedItems}
onApply={setMultipleSelectedItems}
/>
<FilterButton
showResetButton
multiple={false}
name="Single fruit"
items={items}
defaultItems={defaultItems}
selectedItems={singleSelectedItems}
onApply={setSingleSelectedItems}
/>
</div>
);
}
Disabled
function MyFilterButton() {
const items = [
{
label: 'apple',
value: 'apple'
},
{
label: 'banana',
value: 'banana'
}
];
const initialSelectedItems = [
{
label: 'apple',
value: 'apple'
}
];
const [selectedItems, setSelectedItems] = useState(initialSelectedItems);
return (
<FilterButton
name="Fruits"
items={items}
selectedItems={selectedItems}
onApply={setSelectedItems}
disabled
/>
);
}
DisableSort
function MyFilterButton() {
const items = [
{
label: 'apple',
value: 'apple'
},
{
label: 'banana',
value: 'banana'
},
{
label: 'orange',
value: 'orange'
},
{
label: 'cherry',
value: 'cherry'
},
{
label: 'peach',
value: 'peach'
},
{
label: 'pear',
value: 'pear'
},
{
label: 'grapefruit',
value: 'grapefruit'
},
{
label: 'blackberry',
value: 'blackberry'
},
{
label: 'strawberry',
value: 'strawberry'
},
{
label: 'pineapple',
value: 'pineapple'
}
];
const initialSelectedItems = [
{
label: 'pineapple',
value: 'pineapple'
}
];
const [selectedItems, setSelectedItems] = useState(initialSelectedItems);
return (
<FilterButton
name="Fruits"
items={items}
selectedItems={selectedItems}
onApply={setSelectedItems}
disableSort
/>
);
}
DisableSort - Custom Sorting with disabled default sorting
Here is an example of using custom sorting when defaut sorting is disabled.
function MyFilterButton() {
const items = [
{
label: 'Cyprus (CY)',
value: 'cyprus'
},
{
label: 'United States (US)',
value: 'united_states'
},
{
label: 'United Kingdom (UK)',
value: 'united_kingdom'
},
{
label: 'Belgium (BE)',
value: 'belgium'
},
{
label: 'Germany (DE)',
value: 'germany'
},
{
label: 'Russia (RU)',
value: 'russia'
},
{
label: 'Belarus (BY)',
value: 'belarus'
},
{
label: 'Italy (IT)',
value: 'italy'
},
{
label: 'China (CN)',
value: 'china'
},
{
label: 'France (FR)',
value: 'france'
}
];
const [selectedItems, setSelectedItems] = useState([]);
return (
<FilterButton
showResetButton
name="Countries"
items={items}
sortPredicate={(a, b, searchValue) => {
const abbrRegex = new RegExp(`\\b${searchValue}\\b`, 'gi');
return (
Number(abbrRegex.test(b.label)) - Number(abbrRegex.test(a.label))
);
}}
selectedItems={selectedItems}
onApply={setSelectedItems}
disableSort
/>
);
}
Disable Sort when less items
Sorting is disabled by default when there are less than 6 items. This does not apply to search results.
function MyFilterButton() {
const items = [
{
label: 'apple',
value: 'apple'
},
{
label: 'banana',
value: 'banana'
},
{
label: 'orange',
value: 'orange'
},
{
label: 'cherry',
value: 'cherry'
},
{
label: 'pineapple',
value: 'pineapple'
}
];
const initialSelectedItems = [
{
label: 'pineapple',
value: 'pineapple'
}
];
const [selectedItems, setSelectedItems] = useState(initialSelectedItems);
return (
<FilterButton
name="Fruits"
items={items}
selectedItems={selectedItems}
onApply={setSelectedItems}
disableSort
/>
);
}
Loading
You can use a isLoading property in order to display the loading indicator.
function MyFilterButton() {
const items = [
{
label: 'apple',
value: 'apple'
},
{
label: 'banana',
value: 'banana'
},
{
label: 'orange',
value: 'orange'
},
{
label: 'cherry',
value: 'cherry'
},
{
label: 'pear',
value: 'pear'
},
{
label: 'blackberry',
value: 'blackberry'
},
{
label: 'strawberry',
value: 'strawberry'
},
{
label: 'pineapple',
value: 'pineapple'
}
];
const initialSelectedItems = [
{
label: 'apple',
value: 'apple'
}
];
const [selectedItems, setSelectedItems] = useState(initialSelectedItems);
return (
<FilterButton
name="Fruits"
items={items}
selectedItems={selectedItems}
onApply={setSelectedItems}
isLoading
/>
);
}
onReset
You can use onReset property to override the behavior of reset button.
The "initial selected items" are passed as argument to onReset and the returned items will be the desired final selection.
function MyFilterButton() {
const items = [
{
label: 'apple',
value: 'apple'
},
{
label: 'banana',
value: 'banana'
}
];
const initialSelectedItems = [
{
label: 'apple',
value: 'apple'
}
];
const onResetReturnInitialSelectedItems = (initialSelectedItems) =>
initialSelectedItems;
const [selectedItems, setSelectedItems] = useState(initialSelectedItems);
return (
<FilterButton
name="Fruits"
items={items}
selectedItems={selectedItems}
onApply={setSelectedItems}
onReset={onResetReturnInitialSelectedItems}
showResetButton
/>
);
}
RenderItem
You can use a renderItem property to define custom render function for filter items.
The filter uses the virtualization so if you are about to change the height of items do not forget to specify an itemSize property.
function MyFilterButton() {
const apps = [
{
label: 'apple',
value: 'apple',
appId: 'com.adjust.insights'
},
{
label: 'banana',
value: 'banana',
appId: 'com.adjust.insights'
},
{
label: 'orange',
value: 'orange',
appId: 'com.adjust.insights'
}
];
const initialSelectedItems = [
{
label: 'banana',
value: 'banana',
appId: 'com.adjust.insights'
}
];
const [selectedItems, setSelectedItems] = useState(initialSelectedItems);
const renderItem = ({ label, appId }) => (
<div
style={{
display: 'flex',
alignItems: 'center',
width: '100%'
}}
>
<AppIcon appId={appId} size="small" css={{ marginRight: Spacing10 }} />
<span style={{ flex: 1, textAlign: 'left' }}>{label}</span>
<Icon
size="small"
name="PlatformAndroidFilled"
css={{ marginLeft: Spacing10 }}
/>
</div>
);
return (
<FilterButton
name="Fruits"
items={apps}
selectedItems={selectedItems}
onApply={setSelectedItems}
renderItem={renderItem}
itemSize={48}
/>
);
}
Custom List Component
You can use a customList property to define custom component for filter items.
Utilize this property to customize the component of the specific filter items. Please keep in mind that you will be responsible for managing styles and keyboard navigation if you opt to pass a custom component. This functionality is most effectively employed in conjunction with the FilterButtonContext context.
function MyFilterButton() {
const CustomListComponent = ({
label,
value,
checked,
onClick,
onKeyDown
}) => {
const context = useContext(FilterButtonContext);
const {
setSelectedItems,
selectedItems,
setSearchValue,
setAreCheckedItemsChanged
} = context;
console.log({ selectedItems });
return (
<div style={{ paddingLeft: '10px' }}>
<Switch
checked={checked}
size="small"
label={label}
labelPosition="right"
onChange={onClick}
onKeyDown={onKeyDown}
/>
</div>
);
};
const apps = [
{
label: 'apple',
value: 'apple'
},
{
label: 'banana',
value: 'banana'
},
{
label: 'orange',
value: 'orange'
}
];
const initialSelectedItems = [
{
label: 'banana',
value: 'banana'
}
];
const [initialValues, setInitialValues] = useState(initialSelectedItems);
return (
<FilterButton
name="Fruits"
items={apps}
selectedItems={initialValues}
onApply={setInitialValues}
customList={CustomListComponent}
itemSize={48}
/>
);
}
Mode Shifter
In FilterButton we have a mode shifter which can be enabled when modeShifter is true and onModeChange handler is provided.
We have 2 mode include and exclude, which can be controlled using onModeChange handler which uses an argument of either of 2 modes.
function MyFilterButton() {
const items = [
{
label: 'apple',
value: 'apple'
},
{
label: 'banana',
value: 'banana'
},
{
label: 'orange',
value: 'orange'
},
{
label: 'cherry',
value: 'cherry'
},
{
label: 'peach',
value: 'peach'
},
{
label: 'pear',
value: 'pear'
},
{
label: 'grapefruit',
value: 'grapefruit'
},
{
label: 'blackberry',
value: 'blackberry'
},
{
label: 'strawberry',
value: 'strawberry'
},
{
label: 'pineapple',
value: 'pineapple'
}
];
const [selectedItems, setSelectedItems] = useState(items);
const [modeType, setModeType] = useState('include');
const onModeChange = (value) => {
setModeType(value)
};
const onApplyToFilter = (selectedItems, mode) => {
console.log(selectedItems, mode);
setSelectedItems(selectedItems)
}
return (
<FilterButton
name="Fruits"
items={items}
selectedItems={selectedItems}
onApply={onApplyToFilter}
showResetButton
modeShifter
modeType={modeType}
onModeChange={onModeChange}
/>
);
}
You can also change the Mode labels using the modeLabels property.
function MyFilterButton() {
const items = [
{
label: 'apple',
value: 'apple'
},
{
label: 'banana',
value: 'banana'
},
{
label: 'orange',
value: 'orange'
},
{
label: 'cherry',
value: 'cherry'
},
{
label: 'peach',
value: 'peach'
},
{
label: 'pear',
value: 'pear'
},
{
label: 'grapefruit',
value: 'grapefruit'
},
{
label: 'blackberry',
value: 'blackberry'
},
{
label: 'strawberry',
value: 'strawberry'
},
{
label: 'pineapple',
value: 'pineapple'
}
];
const [selectedItems, setSelectedItems] = useState(items);
const [modeType, setModeType] = useState('include');
const onModeChange = (value) => {
setModeType(value)
};
const modeLabels = {
include: 'enthalten',
exclude: 'ausschließen'
}
return (
<FilterButton
name="Fruits"
items={items}
selectedItems={selectedItems}
onApply={setSelectedItems}
showResetButton
modeShifter
modeType={modeType}
onModeChange={onModeChange}
modeLabels={modeLabels}
/>
);
}
RenderValue
You can use a renderValue property to define custom render function for the filter value.
When specified this function is used to render a custom element within the trigger.
function MyFilterButton() {
const items = [
{
label: 'apple',
value: 'apple'
},
{
label: 'banana',
value: 'banana'
}
];
const initialSelectedItems = [
{
label: 'apple',
value: 'apple'
}
];
const [selectedItems, setSelectedItems] = useState(initialSelectedItems);
const renderValue = () => {
return (
<div style={{ display: 'flex', alignItems: 'center' }}>
<Icon name="CogWheel" css={{ marginRight: Spacing10 }} />
<span>All fruits</span>
<Badge
color="negative"
label="Custom label"
css={{ marginLeft: Spacing10 }}
/>
</div>
);
};
return (
<FilterButton
name="Fruits"
items={items}
selectedItems={selectedItems}
onApply={setSelectedItems}
renderValue={renderValue}
/>
);
}
You can use a showResetButton property in order to display the reset button.
The reset button selects all option items.
function MyFilterButton() {
const items = [
{
label: 'apple',
value: 'apple'
},
{
label: 'banana',
value: 'banana'
}
];
const initialSelectedItems = [
{
label: 'apple',
value: 'apple'
}
];
const [selectedItems, setSelectedItems] = useState(initialSelectedItems);
return (
<FilterButton
name="Fruits"
items={items}
selectedItems={selectedItems}
onApply={setSelectedItems}
showResetButton
/>
);
}
The menu list is available in three sizes: small, medium and large can be accessed using menuSize prop.
function MyFilterButton() {
const items = [
{
label: 'apple',
value: 'apple'
},
{
label: 'banana',
value: 'banana'
}
];
const initialSelectedItems = [
{
label: 'apple',
value: 'apple'
}
];
const [selectedItems, setSelectedItems] = useState(initialSelectedItems);
return (
<div style={{ display: 'flex', gap: Spacing10 }}>
<FilterButton
name="Fruits"
items={items}
selectedItems={selectedItems}
onApply={setSelectedItems}
menuSize="small"
/>
<FilterButton
name="Fruits"
items={items}
selectedItems={selectedItems}
onApply={setSelectedItems}
menuSize="medium"
/>
<FilterButton
name="Fruits"
items={items}
selectedItems={selectedItems}
onApply={setSelectedItems}
menuSize="large"
/>
</div>
);
}
Single Value Selection
You can use multiple property to define if you want to have multiple or single selection for defined options.
function MyFilterButton() {
const items = [
{
label: 'apple',
value: 'apple'
},
{
label: 'banana',
value: 'banana'
},
{
label: 'kiwi',
value: 'kiwi'
},
{
label: 'pear',
value: 'pear'
},
{
label: 'dragon fruit',
value: 'dragon fruit'
},
{
label: 'plum',
value: 'plum'
},
{
label: 'tangerine',
value: 'tangerine'
},
{
label: 'durian',
value: 'durian'
},
{
label: 'peach',
value: 'peach'
},
{
label: 'mango',
value: 'mango'
}
];
const initialSelectedItems = [
{
label: 'apple',
value: 'apple'
}
];
const [selectedItems, setSelectedItems] = useState(initialSelectedItems);
return (
<FilterButton
showResetButton
multiple={false}
name="Fruits"
items={items}
selectedItems={selectedItems}
onApply={setSelectedItems}
/>
);
}
Translate
You can use a getElementLabel property to define the text for all elements within the Filter.
This function will be called with one of the following values as an argument:
type FilterButtonTextElements =
| 'apply-button'
| 'reset-button'
| 'select-all-default'
| 'select-all-searched'
| 'loading-message'
| 'not-found-message'
| 'all-selected-badge-label'
| 'search-input-placeholder'
Each value matches the element within the Filter, e.g. 'apply-button' specifies the label for the Apply button etc.
function MyFilterButton() {
const items = [
{
label: 'apple',
value: 'apple'
},
{
label: 'banana',
value: 'banana'
},
{
label: 'orange',
value: 'orange'
},
{
label: 'cherry',
value: 'cherry'
},
{
label: 'peach',
value: 'peach'
},
{
label: 'pear',
value: 'pear'
},
{
label: 'grapefruit',
value: 'grapefruit'
},
{
label: 'blackberry',
value: 'blackberry'
},
{
label: 'strawberry',
value: 'strawberry'
},
{
label: 'pineapple',
value: 'pineapple'
}
];
const initialSelectedItems = [
{
label: 'apple',
value: 'apple'
}
];
const [selectedItems, setSelectedItems] = useState(initialSelectedItems);
const getElementLabel = (element) => {
if (element === 'apply-button') {
return 'Hello';
}
return 'world';
};
return (
<FilterButton
name="Fruits"
items={items}
selectedItems={selectedItems}
onApply={setSelectedItems}
getElementLabel={getElementLabel}
/>
);
}
Props
|
selectedItems * Array of options that populates the filter button. | | — |
items * Array of items that populate the filter button.
The item has two required properties of type string: value and label.
It can be extended with any additional properties. | | — |
name * The name of the Filter. It will be used for displaying the value for Select Button | | — |
multiple Use this prop to switch between multiple and single selections | | true |
id Native HTML attribute: Link .
Internally, this component uses a random id. We use it to associate an input with a label element.
As the random id might break snapshot tests it can be overridden by setting an explicit id. | | — |
defaultItems Array of options which will be selected once user will reset selection | | — |
disabled Use this prop if the component should not be interactive | | — |
getElementLabel Use this prop to override the default elements texts and labels.
FilterButtonTextElements contains elements:
| 'apply-button'
| 'reset-button'
| 'select-all-default'
| 'select-all-searched'
| 'loading-message'
| 'not-found-message'
| 'all-selected-badge-label'
| 'search-input-placeholder' | ((element: FilterButtonTextElements) => string)
| — |
isLoading Use this prop if the component should display loading indicator. | | — |
itemSize The base height of every item within the Filter. | | 32 |
size The size of the FilterAnchor. | | "small" |
menuSize The size of the FilterList. | "small" | "medium" | "large"
| "small" |
showResetButton Use this prop if the component should display the Reset button inside the Filter. | | — |
onReset Use this prop to override the default behavior of the handler called when a user clicks
on Reset button. Returned items will be the ones selected after handler is applied. | ((initialSelectedItems: T[]) => T[])
| — |
onApply The handler will be called when a user closes the Filter. | ((selectedItems: T[], currentModeType?: modeType) => void)
| — |
renderItem Use this prop to override the default rendering function for Filter items. | | — |
customList Use this prop to render a custom list component for each Filter items | | — |
searchPredicate Use this prop to override the default search function.
The default function make a local comparing between an item label and a search string. | | — |
sortPredicate Use this prop to custom sort filtered options
By default options will come in order defined in useSortedItems hook | | — |
renderValue Use this prop to override the default rendering function for the Filter anchor. | (<T extends FilterItem>(selectedItems: T[]) => ReactNode)
| — |
aria-label Provide at least one label(visual or non-visual) property for better accessibility. Check Accessibility page for more info: Link | | — |
aria-labelledby Provide at least one label(visual or non-visual) property for better accessibility. Check Accessibility page for more info: Link | | — |
zIndex Use this prop if you need to custom z-index for filter content | | — |
showSelectAll Boolean prop showing Select all checkbox | | true |
showSearch Boolean prop showing Search input field | | true |
disableSort disable sorting | | false |
modeShifter This is a boolean prop to show the mode shifter | | — |
modeType This is the modeType to either include or exclude | | — |
modeLabels Label string for modeType | | — |
onModeChange The handler will be called when a user change the mode. | | — |
data-{foo} Data attributes can be used by testing libraries to retrieve components or assert their existence | | — |
| * - the prop is required. |