Filter Select
A select with a built-in search field for filtering its options.
Usage guidelines
- Use for modest option lists: Choose
FilterSelectwhen users select one or more predefined values and need search to narrow a manageable list. Use Select when search is unnecessary. - Prefer Combobox for large or remote data: Use Combobox when the input is the control or the list is large, virtualized, or asynchronously loaded. Use Autocomplete when users can enter values that are not in the list.
- Name both controls:
<FilterSelect.Label>labels the select trigger. Give<FilterSelect.Input>a separate accessible name witharia-label,aria-labelledby, or a visible native<label>.
Anatomy
Import the component and assemble its parts:
items is required because it is the data source used to filter the list. Render the items with a function child of <FilterSelect.List> so the rendered entry stays associated with its data.
Examples
Rendering from items
items can be an array of entries, an object map, or grouped entries. Each entry has a value and label:
Matching keywords
Add keywords to an item when users should be able to find it using terms that are not displayed in its label:
The default filter matches the entry’s label and its keywords. Keywords are not rendered as part of the option.
Custom matching
Pass filter to change how entries match the query. The callback receives the item from items and the trimmed query. Parameterize FilterSelectFilter with the item type when declaring a reusable filter:
When a custom filter is provided, it is authoritative. Inspect item.keywords inside it if they should also match.
Controlled query
Use inputValue and onInputValueChange when the query needs to be synchronized with application state. defaultInputValue sets the initial query for uncontrolled usage.
The query is cleared when the popup closes. If the query is controlled, update the value in onInputValueChange for the clear and close events as well as for typing.
Grouped options
Use grouped entries with <FilterSelect.Group>, <FilterSelect.GroupLabel>, and <FilterSelect.Collection>:
Groups with no matching options are removed from the rendered list.
API reference
Root
namestring—
- Name
- Description
Identifies the field when a form is submitted.
- Type
defaultValueUnion—
- Name
- Description
The uncontrolled value of the select when it’s initially rendered.
To render a controlled select, use the
valueprop instead.- Type
valueUnion—
- Name
- Description
The value of the select. Use when controlled.
- Type
onValueChangefunction—
- Name
- Description
Event handler called when the selected value changes.
- Type
defaultInputValuestring—
- Description
The uncontrolled filter query when the select is initially rendered. To render a controlled query, use the
inputValueprop instead.- Type
inputValuestring—
- Name
- Description
The filter query. Use when controlled. The query is cleared when the popup closes.
- Type
onInputValueChangefunction—
- Description
Event handler called when the filter query changes.
- Type
defaultOpenbooleanfalse
- Name
- Description
Whether the popup is initially open.
To render a controlled select, use the
openprop instead.- Type
- Default
false
openboolean—
- Name
- Description
Whether the popup is currently open.
- Type
onOpenChangefunction—
- Name
- Description
Event handler called when the popup is opened or closed.
- Type
highlightItemOnHoverbooleantrue
- Description
Whether moving the pointer over items should highlight them. Disabling this prop allows CSS
:hoverto be differentiated from the:focus(data-highlighted) state.- Type
- Default
true
actionsRefReact.RefObject<SelectRootActions | null>—
- Name
- Description
A ref to imperative actions.
unmount: Manually unmounts the select. Call this after any externally controlled closing animation finishes.
- Type
autoCompletestring—
- Name
- Description
Provides a hint to the browser for autofill.
- Type
filterFilterSelectFilter<FilterSelectItemData>—
- Name
- Description
Replaces the default case-insensitive substring matching for item labels. Receives an entry from
itemsand the trimmed query. When provided, this function is authoritative; inspect the entry’s keywords in the callback if they should also match.- Type
formstring—
- Name
- Description
Identifies the form that owns the hidden input. Useful when the select is rendered outside the form.
- Type
isItemEqualToValuefunction—
- Description
Custom comparison logic used to determine if a select item value matches the current selected value. Useful when item values are objects without matching referentially. Defaults to
Object.iscomparison.- Type
itemToStringLabelfunction—
- Description
When the item values are objects (
<Select.Item value={object}>), this function converts the object value to a string representation for display in the trigger. If the shape of the object is{ value, label }, the label will be used automatically without needing to specify this prop.- Type
itemToStringValuefunction—
- Description
When the item values are objects (
<Select.Item value={object}>), this function converts the object value to a string representation for form submission. If the shape of the object is{ value, label }, the value will be used automatically without needing to specify this prop.- Type
itemsFilterSelectItems<Value, FilterSelectItemData>—
- Name
- Description
Data structure of the items rendered in the popup, and the source the query filters. Required: filtering narrows this data before the list renders. Pass
undefinedwhile the data is loading; an empty collection is treated as loaded and clears unavailable values.Render the entries with a function child of
<FilterSelect.List>, or of<FilterSelect.Collection>inside a group.- Type
localeIntl.LocalesArgument—
- Name
- Description
Locale used when comparing an item against the query. Defaults to the runtime’s default locale.
- Type
modalbooleantrue
- Name
- Description
Determines if the select enters a modal state when open.
true: user interaction is limited to the select: document page scroll is locked and pointer interactions on outside elements are disabled.false: user interaction with the rest of the document is allowed.
On touch devices, a
truemodal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.- Type
- Default
true
multiplebooleanfalse
- Name
- Description
Whether multiple items can be selected.
- Type
- Default
false
onOpenChangeCompletefunction—
- Description
Event handler called after any animations complete when the select popup is opened or closed.
- Type
disabledbooleanfalse
- Name
- Description
Whether the component should ignore user interaction.
- Type
- Default
false
readOnlybooleanfalse
- Name
- Description
Whether the user should be unable to choose a different option from the select popup.
- Type
- Default
false
requiredbooleanfalse
- Name
- Description
Whether the user must choose a value before submitting a form.
- Type
- Default
false
inputRefReact.Ref<HTMLInputElement>—
- Name
- Description
A ref to access the hidden input element.
- Type
idstring—
- Name
- Description
The id of the Select.
- Type
childrenReact.ReactNode—
- Name
- Type
FilterSelect.Root.StateHide
FilterSelect.Root.ActionsHide
FilterSelect.Root.ChangeEventReasonHide
FilterSelect.Root.ChangeEventDetailsHide
FilterSelect.Root.InputValueChangeEventDetailsHide
FilterSelect.Root.InputValueChangeEventReasonHide
Label
An accessible label that is automatically associated with the select trigger.
Renders a <div> element.
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.Label.StateHide
Trigger
nativeButtonbooleantrue
- Name
- Description
Whether the component renders a native
<button>element when replacing it via therenderprop. Set tofalseif the rendered element is not a button (for example,<div>).- Type
- Default
true
disabledboolean—
- Name
- Description
Whether the component should ignore user interaction.
- Type
childrenReact.ReactNode—
- Name
- Type
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.Trigger.StateHide
Value
A text label of the currently selected item.
Renders a <span> element.
placeholderReact.ReactNode—
- Name
- Description
The placeholder value to display when no value is selected. This is overridden by
childrenif specified, or by a null item’s label initems.- Type
children| React.ReactNode
| ((value: any) => React.ReactNode)—
| ((value: any) => React.ReactNode)
- Name
- Description
Accepts a function that returns a
ReactNodeto format the selected value.- Type
- Example
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.Value.StateHide
Icon
An icon that indicates that the trigger button opens a select popup.
Renders a <span> element.
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.Icon.StateHide
Portal
A portal element that moves the popup to a different part of the DOM.
By default, the portal element is appended to <body>.
Renders a <div> element.
containerUnion—
- Name
- Description
A parent element to render the portal element into.
- Type
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.Portal.StateHide
Backdrop
An overlay displayed beneath the select popup.
Renders a <div> element.
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.Backdrop.StateHide
Positioner
disableAnchorTrackingbooleanfalse
- Description
Whether to disable the popup from tracking any layout shift of its positioning anchor.
- Type
- Default
false
alignAlign'center'
- Name
- Description
How to align the popup relative to the specified side.
- Type
- Default
'center'
alignOffsetnumber | OffsetFunction0
- Name
- Description
Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment.
The function takes a
dataobject parameter with the following properties:data.anchor: the dimensions of the anchor element with propertieswidthandheight.data.positioner: the dimensions of the positioner element with propertieswidthandheight.data.side: which side of the anchor element the positioner is aligned against.data.align: how the positioner is aligned relative to the specified side.
- Type
- Default
0- Example
sideSide'bottom'
- Name
- Description
Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
- Type
- Default
'bottom'
sideOffsetnumber | OffsetFunction0
- Name
- Description
Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment.
The function takes a
dataobject parameter with the following properties:data.anchor: the dimensions of the anchor element with propertieswidthandheight.data.positioner: the dimensions of the positioner element with propertieswidthandheight.data.side: which side of the anchor element the positioner is aligned against.data.align: how the positioner is aligned relative to the specified side.
- Type
- Default
0- Example
arrowPaddingnumber5
- Name
- Description
Minimum distance to maintain between the arrow and the edges of the popup.
Use it to prevent the arrow element from hanging out of the rounded corners of a popup.
- Type
- Default
5
anchorUnion—
- Name
- Description
An element to position the popup against. By default, the popup will be positioned against the trigger.
- Type
collisionAvoidanceCollisionAvoidance—
- Description
Determines how to handle collisions when positioning the popup.
sidecontrols overflow on the preferred placement axis (top/bottomorleft/right):'flip': keep the requested side when it fits; otherwise try the opposite side (topandbottom, orleftandright).'shift': never change side; keep the requested side and move the popup within the clipping boundary so it stays visible.'none': do not correct side-axis overflow.
aligncontrols overflow on the alignment axis (start/center/end):'flip': keep side, but swapstartandendwhen the requested alignment overflows.'shift': keep side and requested alignment, then nudge the popup along the alignment axis to fit.'none': do not correct alignment-axis overflow.
fallbackAxisSidecontrols fallback behavior on the perpendicular axis when the preferred axis cannot fit:'start': allow perpendicular fallback and try the logical start side first (topbeforebottom, orleftbeforerightin LTR).'end': allow perpendicular fallback and try the logical end side first (bottombeforetop, orrightbeforeleftin LTR).'none': do not fallback to the perpendicular axis.
When
sideis'shift', explicitly settingalignonly supports'shift'or'none'. Ifalignis omitted, it defaults to'flip'.- Type
- Example
collisionBoundaryBoundary'clipping-ancestors'
- Description
An element or a rectangle that delimits the area that the popup is confined to.
- Type
- Default
'clipping-ancestors'
collisionPaddingPadding5
- Name
- Description
Additional space to maintain from the edge of the collision boundary.
- Type
- Default
5
stickybooleanfalse
- Name
- Description
Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.
- Type
- Default
false
positionMethod'absolute' | 'fixed''absolute'
- Name
- Description
Determines which CSS
positionproperty to use.- Type
- Default
'absolute'
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.Positioner.PropsHide
Re-Export of Positioner props as FilterSelectPositionerProps
FilterSelect.Positioner.StateHide
Popup
finalFocusUnion—
- Name
- Description
Determines the element to focus when the select popup is closed.
false: Do not move focus.true: Move focus based on the default behavior (trigger or previously focused element).RefObject: Move focus to the ref element.function: Called with the interaction type (mouse,touch,pen, orkeyboard). Return an element to focus,trueto use the default behavior, orfalse/undefinedto do nothing.
- Type
childrenReact.ReactNode—
- Name
- Type
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.Popup.StateHide
Input
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.Input.StateHide
Clear
nativeButtonbooleantrue
- Name
- Description
Whether the component renders a native
<button>element when replacing it via therenderprop. Set tofalseif the rendered element is not a button (for example,<div>).- Type
- Default
true
disabledbooleanfalse
- Name
- Description
Whether the component should ignore user interaction.
- Type
- Default
false
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.Clear.StateHide
Empty
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.Empty.StateHide
List
children| React.ReactNode
| ((item: any, index: number) => React.ReactNode)—
| ((item: any, index: number) => React.ReactNode)
- Name
- Description
A function child renders one node per entry from the root’s
itemsprop, the same shapeSelect.Collectionaccepts.- Type
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.List.StateHide
Collection
Renders list items from the root’s data source. Doesn’t render its own HTML element.
If rendering a flat list, pass a function child to the List component instead, which implicitly wraps it.
children*(item: any, index: number) => React.ReactNode—
- Name
- Type
FilterSelect.Collection.PropsHide
Re-Export of Collection props as FilterSelectCollectionProps
FilterSelect.Collection.StateHide
Arrow
Displays an element positioned against the select popup anchor.
Renders a <div> element.
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.Arrow.StateHide
Item
labelstring—
- Name
- Description
Specifies the text label to use during keyboard text navigation.
Defaults to the item text content if not provided.
- Type
valueanynull
- Name
- Description
A unique value that identifies this select item.
- Type
- Default
null
keywordsstring[]—
- Name
- Type
nativeButtonbooleanfalse
- Name
- Description
Whether the component renders a native
<button>element when replacing it via therenderprop. Set totrueif the rendered element is a native button.- Type
- Default
false
disabledbooleanfalse
- Name
- Description
Whether the component should ignore user interaction.
- Type
- Default
false
childrenReact.ReactNode—
- Name
- Type
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.Item.StateHide
ItemText
A text label of the select item.
Renders a <div> element.
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.ItemText.StateHide
ItemIndicator
Indicates whether the select item is selected.
Renders a <span> element.
childrenReact.ReactNode—
- Name
- Type
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
keepMountedboolean—
- Name
- Description
Whether to keep the HTML element in the DOM when the item is not selected.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.ItemIndicator.PropsHide
Re-Export of ItemIndicator props as FilterSelectItemIndicatorProps
FilterSelect.ItemIndicator.StateHide
Group
itemsany[]—
- Name
- Description
The items of this group. When provided, child
Collectioncomponents will use these items.- Type
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.Group.StateHide
GroupLabel
An accessible label that is automatically associated with its parent group.
Renders a <div> element.
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.GroupLabel.PropsHide
Re-Export of GroupLabel props as FilterSelectGroupLabelProps
FilterSelect.GroupLabel.StateHide
ScrollUpArrow
An element that scrolls the select popup up when hovered. Does not render when using touch input.
Renders a <div> element.
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
keepMountedbooleanfalse
- Name
- Description
Whether to keep the HTML element in the DOM while the select popup is not scrollable.
- Type
- Default
false
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.ScrollUpArrow.PropsHide
Re-Export of ScrollUpArrow props as FilterSelectScrollUpArrowProps
FilterSelect.ScrollUpArrow.StateHide
ScrollDownArrow
An element that scrolls the select popup down when hovered. Does not render when using touch input.
Renders a <div> element.
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
keepMountedbooleanfalse
- Name
- Description
Whether to keep the HTML element in the DOM while the select popup is not scrollable.
- Type
- Default
false
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
FilterSelect.ScrollDownArrow.PropsHide
Re-Export of ScrollDownArrow props as FilterSelectScrollDownArrowProps
FilterSelect.ScrollDownArrow.StateHide
Separator
A visual separator between items or groups.
Renders a <div> element.
orientationOrientation'horizontal'
- Name
- Description
The orientation of the separator.
- Type
- Default
'horizontal'
classNamestring | function—
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
styleReact.CSSProperties | function—
- Name
- Description
Style applied to the element, or a function that returns a style object based on the component’s state.
- Type
renderReactElement | function—
- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type