Skip to contents

Filter Select

A select with a built-in search field for filtering its options.

Fruit

Usage guidelines

  • Use for modest option lists: Choose FilterSelect when 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 with aria-label, aria-labelledby, or a visible native <label>.

Anatomy

Import the component and assemble its parts:

Anatomy

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:

Rendering options

Matching keywords

Add keywords to an item when users should be able to find it using terms that are not displayed in its label:

Additional search terms

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:

Custom 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.

Controlling the query

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>:

Grouped options

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
Description

The uncontrolled value of the select when it’s initially rendered.

To render a controlled select, use the value prop instead.

Type
valueUnion
Name
Description

The value of the select. Use when controlled.

Type
onValueChangefunction
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 inputValue prop instead.

Type
inputValuestring
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
Description

Whether the popup is initially open.

To render a controlled select, use the open prop instead.

Type
Default
false
openboolean
Name
Description

Whether the popup is currently open.

Type
onOpenChangefunction
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 :hover to be differentiated from the :focus (data-highlighted) state.

Type
Default
true
actionsRefReact.RefObject<SelectRootActions | null>
Description

A ref to imperative actions.

  • unmount: Manually unmounts the select. Call this after any externally controlled closing animation finishes.
Type
autoCompletestring
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 items and the trimmed query. When provided, this function is authoritative; inspect the entry’s keywords in the callback if they should also match.

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.is comparison.

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 undefined while 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 true modal 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
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
Description

Whether the component should ignore user interaction.

Type
Default
false
readOnlybooleanfalse
Description

Whether the user should be unable to choose a different option from the select popup.

Type
Default
false
requiredbooleanfalse
Description

Whether the user must choose a value before submitting a form.

Type
Default
false
inputRefReact.Ref<HTMLInputElement>
Description

A ref to access the hidden input element.

Type
idstring
Name
Description

The id of the Select.

Type
childrenReact.ReactNode
Type

FilterSelect.Root.PropsHide

Re-Export of Root props as FilterSelectRootProps

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
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 ReactElement or a function that returns the element to render.

Type

FilterSelect.Label.PropsHide

Re-Export of Label props as FilterSelectLabelProps

FilterSelect.Label.StateHide

Trigger

nativeButtonbooleantrue
Description

Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>).

Type
Default
true
disabledboolean
Description

Whether the component should ignore user interaction.

Type
childrenReact.ReactNode
Type
classNamestring | function
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 ReactElement or a function that returns the element to render.

Type

FilterSelect.Trigger.PropsHide

Re-Export of Trigger props as FilterSelectTriggerProps

FilterSelect.Trigger.StateHide

Value

A text label of the currently selected item. Renders a <span> element.

placeholderReact.ReactNode
Description

The placeholder value to display when no value is selected. This is overridden by children if specified, or by a null item’s label in items.

Type
children| React.ReactNode
| ((value: any) => React.ReactNode)
Description

Accepts a function that returns a ReactNode to format the selected value.

Type
Example
classNamestring | function
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 ReactElement or a function that returns the element to render.

Type

FilterSelect.Value.PropsHide

Re-Export of Value props as FilterSelectValueProps

FilterSelect.Value.StateHide

Icon

An icon that indicates that the trigger button opens a select popup. Renders a <span> element.

classNamestring | function
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 ReactElement or a function that returns the element to render.

Type

FilterSelect.Icon.PropsHide

Re-Export of Icon props as FilterSelectIconProps

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
Description

A parent element to render the portal element into.

Type
classNamestring | function
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 ReactElement or a function that returns the element to render.

Type

FilterSelect.Portal.PropsHide

Re-Export of Portal props as FilterSelectPortalProps

FilterSelect.Portal.StateHide

Backdrop

An overlay displayed beneath the select popup. Renders a <div> element.

classNamestring | function
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 ReactElement or a function that returns the element to render.

Type

FilterSelect.Backdrop.PropsHide

Re-Export of Backdrop props as FilterSelectBackdropProps

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
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 data object parameter with the following properties:

  • data.anchor: the dimensions of the anchor element with properties width and height.
  • data.positioner: the dimensions of the positioner element with properties width and height.
  • 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
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 data object parameter with the following properties:

  • data.anchor: the dimensions of the anchor element with properties width and height.
  • data.positioner: the dimensions of the positioner element with properties width and height.
  • 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
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.

side controls overflow on the preferred placement axis (top/bottom or left/right):

  • 'flip': keep the requested side when it fits; otherwise try the opposite side (top and bottom, or left and right).
  • '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.

align controls overflow on the alignment axis (start/center/end):

  • 'flip': keep side, but swap start and end when 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.

fallbackAxisSide controls fallback behavior on the perpendicular axis when the preferred axis cannot fit:

  • 'start': allow perpendicular fallback and try the logical start side first (top before bottom, or left before right in LTR).
  • 'end': allow perpendicular fallback and try the logical end side first (bottom before top, or right before left in LTR).
  • 'none': do not fallback to the perpendicular axis.

When side is 'shift', explicitly setting align only supports 'shift' or 'none'. If align is 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
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'
Description

Determines which CSS position property to use.

Type
Default
'absolute'
classNamestring | function
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 ReactElement or a function that returns the element to render.

Type

FilterSelect.Positioner.PropsHide

Re-Export of Positioner props as FilterSelectPositionerProps

FilterSelect.Positioner.StateHide

finalFocusUnion
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, or keyboard). Return an element to focus, true to use the default behavior, or false/undefined to do nothing.
Type
childrenReact.ReactNode
Type
classNamestring | function
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 ReactElement or a function that returns the element to render.

Type

FilterSelect.Popup.PropsHide

Re-Export of Popup props as FilterSelectPopupProps

FilterSelect.Popup.StateHide

Input

classNamestring | function
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 ReactElement or a function that returns the element to render.

Type

FilterSelect.Input.PropsHide

Re-Export of Input props as FilterSelectInputProps

FilterSelect.Input.StateHide

Clear

nativeButtonbooleantrue
Description

Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>).

Type
Default
true
disabledbooleanfalse
Description

Whether the component should ignore user interaction.

Type
Default
false
classNamestring | function
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 ReactElement or a function that returns the element to render.

Type

FilterSelect.Clear.PropsHide

Re-Export of Clear props as FilterSelectClearProps

FilterSelect.Clear.StateHide

Empty

classNamestring | function
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 ReactElement or a function that returns the element to render.

Type

FilterSelect.Empty.PropsHide

Re-Export of Empty props as FilterSelectEmptyProps

FilterSelect.Empty.StateHide

List

children| React.ReactNode
| ((item: any, index: number) => React.ReactNode)
Description

A function child renders one node per entry from the root’s items prop, the same shape Select.Collection accepts.

Type
classNamestring | function
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 ReactElement or a function that returns the element to render.

Type

FilterSelect.List.PropsHide

Re-Export of List props as FilterSelectListProps

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
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
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 ReactElement or a function that returns the element to render.

Type

FilterSelect.Arrow.PropsHide

Re-Export of Arrow props as FilterSelectArrowProps

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[]
Type
nativeButtonbooleanfalse
Description

Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.

Type
Default
false
disabledbooleanfalse
Description

Whether the component should ignore user interaction.

Type
Default
false
childrenReact.ReactNode
Type
classNamestring | function
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 ReactElement or a function that returns the element to render.

Type

FilterSelect.Item.PropsHide

Re-Export of Item props as FilterSelectItemProps

FilterSelect.Item.StateHide

ItemText

A text label of the select item. Renders a <div> element.

classNamestring | function
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 ReactElement or a function that returns the element to render.

Type

FilterSelect.ItemText.PropsHide

Re-Export of ItemText props as FilterSelectItemTextProps

FilterSelect.ItemText.StateHide

ItemIndicator

Indicates whether the select item is selected. Renders a <span> element.

childrenReact.ReactNode
Type
classNamestring | function
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
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 ReactElement or 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 Collection components will use these items.

Type
classNamestring | function
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 ReactElement or a function that returns the element to render.

Type

FilterSelect.Group.PropsHide

Re-Export of Group props as FilterSelectGroupProps

FilterSelect.Group.StateHide

GroupLabel

An accessible label that is automatically associated with its parent group. Renders a <div> element.

classNamestring | function
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 ReactElement or 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
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
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 ReactElement or 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
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
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 ReactElement or 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'
Description

The orientation of the separator.

Type
Default
'horizontal'
classNamestring | function
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 ReactElement or a function that returns the element to render.

Type

FilterSelect.Separator.PropsHide

Re-Export of Separator props as FilterSelectSeparatorProps

FilterSelect.Separator.StateHide