FilterDropdown

A lightweight filter for a list or table toolbar: a 36px trigger that opens a menu and narrows the list by one attribute. Picks apply at once — there is no Apply step. Single mode is for exclusive values and starts with «All …», which is also the reset; multi mode ticks several values that are OR-ed and clears with the ✕. From eight options the menu gains a search, and in multi mode a "Selected" section on top. Reach for Select inside forms, and for FilterInput when the query combines several attributes and operators.

Source · Storybook

PreviewCode

Usage

import { FilterDropdown, FilterDropdownTrigger } from '@wallarm-org/design-system/FilterDropdown';

Examples

Multi

Multi mode: checkboxes, OR-ed, the menu stays open. The trigger shows the name with the value or a count, and the ✕ (or Backspace on the trigger) clears. Pass your own FilterDropdownClear as the trigger's child to put an analytics id on the ✕.

PreviewCode

Label forms

Every form the trigger takes: dashed while unset, solid with a shadow once set.

PreviewCode

States

Disabled keeps the value readable — the ✕ and the count stay visible, just inert.

PreviewCode

With search

From searchThreshold options (8 by default) the menu gains a search that takes focus on open, and multi mode repeats what was picked in a "Selected" section on top. It is a snapshot: rows stay put while you tick, and it hides while a query is active.

PreviewCode

Groups

A groupBy collection renders one labelled group per entry of useFilterDropdown().groups.

PreviewCode

Hint

hint puts secondary text, such as a count, at the right end of a row, before the check.

PreviewCode

Long labels

The trigger stops at 180px and ellipsises, with the full value on hover; the menu hugs its options up to 360px and wraps longer ones.

PreviewCode

Filter row

The toolbar it is made for: a search, scoped views, then one filter per attribute.

PreviewCode

Controlled

Controlled with value / onValueChange. The handler only ever receives your own values — [] for unset — never the internal «All» or "Selected" ones.

PreviewCode

Props

Prop	Type	Default	Description
title	`string \| undefined`
defaultChecked	`boolean \| undefined`
autoFocus	`boolean \| undefined`
id	`string`		The unique identifier of the machine.
tabIndex	`number \| undefined`
rel	`string \| undefined`
onChange	`ChangeEventHandler<T, Element> \| undefined`
disabled	`boolean \| undefined`	`false`	Whether the select is disabled
asChild	`boolean \| undefined`		Use the provided child element as the default rendered element, combining their props and behavior.
data-testid	`string \| undefined`
positioning	`PositioningOptions \| undefined`		Override default floating positioning (merged with DS defaults).
ids	`ElementIds \| undefined`		The ids of the elements in the select. Useful for composition.
loopFocus	`boolean \| undefined`		Whether to loop the keyboard navigation through the options
closeOnSelect	`boolean \| undefined`		Whether the select should close after an item is selected
open	`boolean \| undefined`		Whether the select menu is open
defaultOpen	`boolean \| undefined`		Whether the select's open state is controlled by the user
composite	`boolean \| undefined`		Whether the select is a composed with other composite widgets like tabs or combobox
onPointerDownOutside	`complex`		Function called when the pointer is pressed down outside the component
onFocusOutside	`complex`		Function called when the focus is moved outside the component
onInteractOutside	`complex`		Function called when an interaction happens outside the component
present	`boolean \| undefined`		Whether the node is present (controlled by the user)
onExitComplete	`VoidFunction \| undefined`		Function called when the animation ends in the closed state
onEnterComplete	`VoidFunction \| undefined`		Function called when the animation ends in the open state
immediate	`boolean \| undefined`		Whether to synchronize the present change immediately or defer it to the next frame
autoComplete	`string \| undefined`		The autocomplete attribute for the hidden select. Enables browser autofill (e.g. "address-level1" for state).
readOnly	`boolean \| undefined`		Whether the select is read-only
required	`boolean \| undefined`		Whether the select is required
invalid	`boolean \| undefined`		Whether the select is invalid
translations	`IntlTranslations \| undefined`		Specifies the localized strings that identifies the accessibility elements and their states
scrollToIndexFn	`((details: ScrollToIndexDetails) => void) \| undefined`		Function to scroll to a specific index
skipAnimationOnMount	`boolean \| undefined`		Whether to allow the initial presence animation.
hideMode	`"display-none" \| "activity"`		How to hide content when mounted but not present. - `'display-none'`: HTML `hidden` attribute. Effects stay alive. - `'activity'`: React 19 `<Activity mode="hidden">`. Effects pause. Requires React 19+.
label *	`string`		Attribute name: trigger text in multi mode, the trigger's aria-label, «Clear {label}».
allLabel	`string \| undefined`	`All`	Single mode: trigger text while unset and the default text of `FilterDropdownAllOption`.
collection *	`ListCollection<T>`		Items to pick from. `groupBy` is supported.
multiple	`boolean \| undefined`	`false`	Checkbox mode: several values, OR-ed, the menu stays open.
value	`string[] \| undefined`		Controlled picked values; `[]` = unset.
defaultValue	`string[] \| undefined`
onValueChange	`((details: FilterDropdownValueChangeDetails<T>) => void) \| undefined`
onOpenChange	`((details: FilterDropdownOpenChangeDetails) => void) \| undefined`
searchThreshold	`number \| undefined`	`DEFAULT_SEARCH_THRESHOLD`	Item count from which the search field and (multi) the "Selected" section appear. Counts the collection's own items only.
filterFn	`((itemString: string, item: T, query: string) => boolean) \| undefined`		Overrides the default case-insensitive match on the item label.
selectedOnTop	`boolean \| undefined`	`true`	Multi mode: pin the picked values under «Selected» on top of the list (from `searchThreshold` items, hidden while searching). Render `FilterDropdownSelected` for it.

FilterDropdownAllOption

Prop	Type	Description
title	`string \| undefined`
defaultChecked	`boolean \| undefined`
defaultValue	`string \| number \| readonly string[] \| undefined`
autoFocus	`boolean \| undefined`
id	`string \| undefined`
tabIndex	`number \| undefined`
rel	`string \| undefined`
onChange	`ChangeEventHandler<T, Element> \| undefined`
asChild	`boolean \| undefined`	Use the provided child element as the default rendered element, combining their props and behavior.
data-testid	`string \| undefined`
variant	`{ default: string; brand: string; destructive: string; }`
inset	`{ true: string; }`
persistFocus	`boolean \| undefined`	Whether hovering outside should clear the highlighted state

FilterDropdownClear

Prop	Type	Default	Description
disabled	`boolean \| undefined`
name	`string \| undefined`
type	`"button" \| "submit" \| "reset" \| undefined`
value	`string \| number \| readonly string[] \| undefined`
defaultChecked	`boolean \| undefined`
defaultValue	`string \| number \| readonly string[] \| undefined`
autoFocus	`boolean \| undefined`
id	`string \| undefined`
tabIndex	`number \| undefined`
title	`string \| undefined`
rel	`string \| undefined`
onChange	`ChangeEventHandler<T, Element> \| undefined`
data-testid	`string \| undefined`

FilterDropdownContent

Prop	Type	Default	Description
title	`string \| undefined`
defaultChecked	`boolean \| undefined`
defaultValue	`string \| number \| readonly string[] \| undefined`
autoFocus	`boolean \| undefined`
id	`string \| undefined`
tabIndex	`number \| undefined`
rel	`string \| undefined`
onChange	`ChangeEventHandler<T, Element> \| undefined`
data-testid	`string \| undefined`

FilterDropdownEmpty

Prop	Type	Default	Description
title	`string \| undefined`
defaultChecked	`boolean \| undefined`
defaultValue	`string \| number \| readonly string[] \| undefined`
autoFocus	`boolean \| undefined`
id	`string \| undefined`
tabIndex	`number \| undefined`
rel	`string \| undefined`
onChange	`ChangeEventHandler<T, Element> \| undefined`
data-testid	`string \| undefined`

FilterDropdownFooter

Prop	Type	Default	Description
title	`string \| undefined`
defaultChecked	`boolean \| undefined`
defaultValue	`string \| number \| readonly string[] \| undefined`
autoFocus	`boolean \| undefined`
id	`string \| undefined`
tabIndex	`number \| undefined`
rel	`string \| undefined`
onChange	`ChangeEventHandler<T, Element> \| undefined`
data-testid	`string \| undefined`

FilterDropdownFooterClear

Prop	Type	Default	Description
title	`string \| undefined`
defaultChecked	`boolean \| undefined`
defaultValue	`string \| number \| readonly string[] \| undefined`
autoFocus	`boolean \| undefined`
id	`string \| undefined`
tabIndex	`number \| undefined`
rel	`string \| undefined`
onChange	`ChangeEventHandler<T, Element> \| undefined`
type	`"button" \| "submit" \| "reset" \| undefined`
disabled	`boolean \| undefined`
name	`string \| undefined`
value	`string \| number \| readonly string[] \| undefined`
data-testid	`string \| undefined`
loading	`{ true: string; }`
fullWidth	`{ true: string; false: string; }`

FilterDropdownGroup

Prop	Type	Description
title	`string \| undefined`
defaultChecked	`boolean \| undefined`
defaultValue	`string \| number \| readonly string[] \| undefined`
autoFocus	`boolean \| undefined`
id	`string \| undefined`
tabIndex	`number \| undefined`
rel	`string \| undefined`
onChange	`ChangeEventHandler<T, Element> \| undefined`
asChild	`boolean \| undefined`	Use the provided child element as the default rendered element, combining their props and behavior.
data-testid	`string \| undefined`

FilterDropdownGroupLabel

Prop	Type	Description
title	`string \| undefined`
defaultChecked	`boolean \| undefined`
defaultValue	`string \| number \| readonly string[] \| undefined`
autoFocus	`boolean \| undefined`
id	`string \| undefined`
tabIndex	`number \| undefined`
rel	`string \| undefined`
onChange	`ChangeEventHandler<T, Element> \| undefined`
asChild	`boolean \| undefined`	Use the provided child element as the default rendered element, combining their props and behavior.
data-testid	`string \| undefined`

FilterDropdownOption

Prop	Type	Description
item *	`T`
hint	`ReactNode`	Secondary text at the right end of the row, such as a count.
title	`string \| undefined`
defaultChecked	`boolean \| undefined`
defaultValue	`string \| number \| readonly string[] \| undefined`
autoFocus	`boolean \| undefined`
id	`string \| undefined`
tabIndex	`number \| undefined`
rel	`string \| undefined`
onChange	`ChangeEventHandler<T, Element> \| undefined`
asChild	`boolean \| undefined`	Use the provided child element as the default rendered element, combining their props and behavior.
data-testid	`string \| undefined`
variant	`{ default: string; brand: string; destructive: string; }`
inset	`{ true: string; }`
persistFocus	`boolean \| undefined`	Whether hovering outside should clear the highlighted state

FilterDropdownSearch

Prop	Type	Description
onChange	`((query: string) => void) \| undefined`	Called after the query changes; the root owns the query itself.
title	`string \| undefined`
pattern	`string \| undefined`
defaultChecked	`boolean \| undefined`
defaultValue	`string \| number \| readonly string[] \| undefined`
autoFocus	`boolean \| undefined`
id	`string \| undefined`
tabIndex	`number \| undefined`
rel	`string \| undefined`
disabled	`boolean \| undefined`
name	`string \| undefined`
alt	`string \| undefined`
height	`string \| number \| undefined`
src	`string \| undefined`
width	`string \| number \| undefined`
autoComplete	`HTMLInputAutoCompleteAttribute \| undefined`
maxLength	`number \| undefined`
minLength	`number \| undefined`
placeholder	`string \| undefined`
readOnly	`boolean \| undefined`
required	`boolean \| undefined`
checked	`boolean \| undefined`
step	`string \| number \| undefined`
accept	`string \| undefined`
max	`string \| number \| undefined`
min	`string \| number \| undefined`
multiple	`boolean \| undefined`
onClear	`(() => void) \| undefined`	Called when the built-in clear button empties the field, before `onChange('')`.
data-testid	`string \| undefined`

FilterDropdownSelected

Prop	Type	Default	Description
label	`ReactNode`	`Selected`	@default 'Selected'
title	`string \| undefined`
defaultChecked	`boolean \| undefined`
defaultValue	`string \| number \| readonly string[] \| undefined`
autoFocus	`boolean \| undefined`
id	`string \| undefined`
tabIndex	`number \| undefined`
rel	`string \| undefined`
onChange	`ChangeEventHandler<T, Element> \| undefined`
asChild	`boolean \| undefined`		Use the provided child element as the default rendered element, combining their props and behavior.
data-testid	`string \| undefined`

FilterDropdownTrigger

Prop	Type	Default	Description
title	`string \| undefined`
defaultChecked	`boolean \| undefined`
defaultValue	`string \| number \| readonly string[] \| undefined`
autoFocus	`boolean \| undefined`
id	`string \| undefined`
tabIndex	`number \| undefined`
rel	`string \| undefined`
onChange	`ChangeEventHandler<T, Element> \| undefined`
type	`"button" \| "submit" \| "reset" \| undefined`
disabled	`boolean \| undefined`
name	`string \| undefined`
value	`string \| number \| readonly string[] \| undefined`
data-testid	`string \| undefined`

#FilterDropdown

#Usage

#Examples

#Multi

#Label forms

#States

#With search

#Groups

#Hint

#Long labels

#Filter row

#Controlled

#Props

#FilterDropdownAllOption

#FilterDropdownClear

#FilterDropdownContent

#FilterDropdownEmpty

#FilterDropdownFooter

#FilterDropdownFooterClear

#FilterDropdownGroup

#FilterDropdownGroupLabel

#FilterDropdownOption

#FilterDropdownSearch

#FilterDropdownSelected

#FilterDropdownTrigger

#Explorer

FilterDropdown

Usage

Examples

Multi

Label forms

States

With search

Groups

Hint

Long labels

Filter row

Controlled

Props

FilterDropdownAllOption

FilterDropdownClear

FilterDropdownContent

FilterDropdownEmpty

FilterDropdownFooter

FilterDropdownFooterClear

FilterDropdownGroup

FilterDropdownGroupLabel

FilterDropdownOption

FilterDropdownSearch

FilterDropdownSelected

FilterDropdownTrigger

Explorer