edbnedbn/ui
ComponentsMapsPDF
GitHub stars
Explorer
Get Started
Components

Combobox

Premium solid combobox with full primitive part coverage, chips, filtering hooks, grouping, status, and portal positioning.

Componentsdocsbase-ui/combobox

Installation

npx shadcn@latest add https://ui.edbn.me/api/analytics/registry/combobox.json

Manual

API Reference

Root

Groups every Autocomplete part and owns value, filtering, highlighting, form, popup, and inline completion state. It does not render an element.

Behavior
itemsreadonly Item[] | readonly Group[]

Items or grouped items used by the list.

filteredItemsreadonly Item[] | readonly Group[]

Externally filtered items to render instead of internal filtering.

filterAutocompleteFilter<Item> | null

Custom item matching function. Pass null to disable internal filtering.

mode'list' | 'both' | 'inline' | 'none'
='list'

Controls list filtering and inline completion behavior.

defaultValuestring

Initial uncontrolled input value.

valuestring

Controlled input value.

defaultOpenboolean
=false

Initial uncontrolled popup open state.

openboolean

Controlled popup open state.

openOnInputClickboolean
=false

Whether clicking the input opens the popup.

autoHighlightboolean | 'always'
=false

Whether the first matching item is highlighted automatically.

keepHighlightboolean
=false

Whether highlighted state is kept when the pointer leaves the list.

highlightItemOnHoverboolean
=true

Whether pointer hover highlights items.

loopFocusboolean
=true

Whether arrow-key navigation loops between the input and list.

gridboolean
=false

Enables grid-style item navigation using Row parts.

inlineboolean
=false

Renders the list inline without a popup.

virtualizedboolean
=false

Marks the list as externally virtualized.

limitnumber
=-1

Maximum number of matching items to display.

localeIntl.LocalesArgument
=runtime locale

Locale used by the default string comparison.

modalboolean
=false

When true, outside interaction and page scroll are limited while open.

submitOnItemClickboolean
=false

Whether choosing an item submits the owning form.

itemToStringValue(item) => string

Converts object item values to the input and form value string.

actionsRefReact.RefObject<{ unmount: () => void }>

Imperative actions for manually unmounting after external animation.

childrenReact.ReactNode

Autocomplete parts.

Events
onValueChange(value, eventDetails) => void

Called when the input value changes.

onOpenChange(open, eventDetails) => void

Called when the popup opens or closes.

onOpenChangeComplete(open) => void

Called after open or close animations complete.

onItemHighlighted(item, eventDetails) => void

Called when the highlighted item changes.

Forms
namestring

Name for the internal form input.

formstring

Id of the form that owns the internal input.

idstring

Id used as the component id base.

inputRefReact.Ref<HTMLInputElement>

Ref for the internal input element.

requiredboolean
=false

Marks the form field as required.

State
disabledboolean
=false

Disables user interaction.

readOnlyboolean
=false

Prevents user edits while preserving value display.

InputGroup

Wraps the input and field controls. Renders a div element.

Styling
classNamestring | ((state) => string)

Class names applied to the rendered element.

styleReact.CSSProperties | ((state) => React.CSSProperties)

Inline styles applied to the rendered element.

Composition
renderReactElement | ((props, state) => ReactElement)

Custom render target while preserving Base UI behavior.

InputGroup data attributes
AttributeDescription
data-popup-openPresent when the popup is open.
data-popup-sideIndicates the side where the popup is positioned.
data-list-emptyPresent when the filtered list has no items.
data-disabledPresent when disabled.
data-readonlyPresent when read-only.
data-validPresent when the field is valid.
data-invalidPresent when the field is invalid.
data-touchedPresent after the field is touched.
data-dirtyPresent after the value changes.
data-filledPresent when the field has a value.
data-focusedPresent when the field has focus.

Input

The text input used to search, filter, and complete items. Renders an input element.

State
disabledboolean
=false

Disables the input.

Styling
classNamestring | ((state) => string)

Class names applied to the rendered element.

styleReact.CSSProperties | ((state) => React.CSSProperties)

Inline styles applied to the rendered element.

Composition
renderReactElement | ((props, state) => ReactElement)

Custom render target while preserving Base UI behavior.

Input data attributes
AttributeDescription
data-popup-openPresent when the popup is open.
data-popup-sideIndicates the side where the popup is positioned.
data-list-emptyPresent when the filtered list has no items.
data-disabledPresent when disabled.
data-readonlyPresent when read-only.
data-validPresent when the field is valid.
data-invalidPresent when the field is invalid.
data-touchedPresent after the field is touched.
data-dirtyPresent after the value changes.
data-filledPresent when the field has a value.
data-focusedPresent when the field has focus.
data-requiredPresent when required.

Trigger

A button that opens or closes the popup. Renders a button element.

State
disabledboolean
=false

Disables the trigger.

Composition
nativeButtonboolean
=true

When false, the part renders with non-native button semantics.

renderReactElement | ((props, state) => ReactElement)

Custom render target while preserving Base UI behavior.

Styling
classNamestring | ((state) => string)

Class names applied to the rendered element.

styleReact.CSSProperties | ((state) => React.CSSProperties)

Inline styles applied to the rendered element.

Trigger data attributes
AttributeDescription
data-popup-openPresent when the popup is open.
data-popup-sideIndicates the side where the popup is positioned.
data-list-emptyPresent when the filtered list has no items.
data-disabledPresent when disabled.
data-readonlyPresent when read-only.
data-validPresent when the field is valid.
data-invalidPresent when the field is invalid.
data-touchedPresent after the field is touched.
data-dirtyPresent after the value changes.
data-filledPresent when the field has a value.
data-focusedPresent when the field has focus.
data-requiredPresent when required.

Icon

An icon slot associated with the field. Renders a span element.

Styling
classNamestring | ((state) => string)

Class names applied to the rendered element.

styleReact.CSSProperties | ((state) => React.CSSProperties)

Inline styles applied to the rendered element.

Composition
renderReactElement | ((props, state) => ReactElement)

Custom render target while preserving Base UI behavior.

Clear

A button that clears the current input value. Renders a button element.

State
disabledboolean
=false

Disables the clear button.

Behavior
keepMountedboolean
=false

Keeps the clear button mounted while hidden.

Composition
nativeButtonboolean
=true

When false, the part renders with non-native button semantics.

renderReactElement | ((props, state) => ReactElement)

Custom render target while preserving Base UI behavior.

Styling
classNamestring | ((state) => string)

Class names applied to the rendered element.

styleReact.CSSProperties | ((state) => React.CSSProperties)

Inline styles applied to the rendered element.

Clear data attributes
AttributeDescription
data-visiblePresent when the clear button is visible.
data-starting-stylePresent before the clear transition starts.
data-ending-stylePresent while the clear transition ends.

Value

Reads the current input value for custom rendering. It does not render its own element.

Composition
childrenReact.ReactNode | ((value: string) => React.ReactNode)

Content or render function receiving the current value.

Portal

Moves the popup subtree to another DOM container. Renders a div element.

Positioning
containerHTMLElement | RefObject | null
=document.body

Container where the portal is mounted.

Behavior
keepMountedboolean
=false

Keeps the portal mounted while the popup is closed.

Styling
classNamestring | ((state) => string)

Class names applied to the rendered element.

styleReact.CSSProperties | ((state) => React.CSSProperties)

Inline styles applied to the rendered element.

Composition
renderReactElement | ((props, state) => ReactElement)

Custom render target while preserving Base UI behavior.

Backdrop

Optional overlay rendered beneath the popup. Renders a div element.

Styling
classNamestring | ((state) => string)

Class names applied to the rendered element.

styleReact.CSSProperties | ((state) => React.CSSProperties)

Inline styles applied to the rendered element.

Composition
renderReactElement | ((props, state) => ReactElement)

Custom render target while preserving Base UI behavior.

Backdrop data attributes
AttributeDescription
data-openPresent when the popup is open.
data-closedPresent when the popup is closed.
data-starting-stylePresent before the backdrop transition starts.
data-ending-stylePresent while the backdrop transition ends.

Positioner

Positions the popup against the input group or a custom anchor. Renders a div element.

Positioning
anchorElement | VirtualElement | RefObject | (() => Element | null)
=trigger

Anchor used for popup positioning.

positionMethod'absolute' | 'fixed'
='absolute'

CSS position strategy for the popup.

side'top' | 'bottom' | 'left' | 'right' | 'inline-start' | 'inline-end'
='bottom'

Preferred side of the anchor.

sideOffsetnumber | OffsetFunction
=0

Distance between anchor and popup.

align'start' | 'center' | 'end'
='center'

Popup alignment on the chosen side.

alignOffsetnumber | OffsetFunction
=0

Offset along the alignment axis.

collisionBoundary'clipping-ancestors' | Element | Element[] | Rect
='clipping-ancestors'

Boundary used for collision detection.

collisionPaddingPadding
=5

Space kept between popup and collision boundary.

collisionAvoidanceCollisionAvoidance

How side and alignment collisions are corrected.

stickyboolean
=false

Keeps the popup visible when the anchor scrolls out of view.

arrowPaddingnumber
=5

Minimum distance between arrow and popup edges.

disableAnchorTrackingboolean
=false

Disables tracking anchor layout shifts.

Styling
classNamestring | ((state) => string)

Class names applied to the rendered element.

styleReact.CSSProperties | ((state) => React.CSSProperties)

Inline styles applied to the rendered element.

Composition
renderReactElement | ((props, state) => ReactElement)

Custom render target while preserving Base UI behavior.

Positioner data attributes
AttributeDescription
data-openPresent when the popup is open.
data-closedPresent when the popup is closed.
data-sideIndicates the resolved popup side.
data-alignIndicates the resolved popup alignment.
data-emptyPresent when no items are shown.
data-anchor-hiddenPresent when the anchor is hidden.
Positioner CSS variables
VariableDescription
--anchor-heightMeasured anchor height.
--anchor-widthMeasured anchor width.
--available-heightAvailable height before collision.
--available-widthAvailable width before collision.
--transform-originOrigin point for transform animations.

Popup

Container for the suggestion list. Renders a div element.

Focus
initialFocusboolean | RefObject | ((openType) => HTMLElement | boolean | null)

Element to focus when the popup opens.

finalFocusboolean | RefObject | ((closeType) => HTMLElement | boolean | null)

Element to focus when the popup closes.

Styling
classNamestring | ((state) => string)

Class names applied to the rendered element.

styleReact.CSSProperties | ((state) => React.CSSProperties)

Inline styles applied to the rendered element.

Composition
renderReactElement | ((props, state) => ReactElement)

Custom render target while preserving Base UI behavior.

Popup data attributes
AttributeDescription
data-openPresent when the popup is open.
data-closedPresent when the popup is closed.
data-sideIndicates the resolved popup side.
data-alignIndicates the resolved popup alignment.
data-emptyPresent when no items are shown.
data-starting-stylePresent before the popup transition starts.
data-ending-stylePresent while the popup transition ends.
data-instantPresent when transitions should be skipped.

Arrow

Displays an element positioned toward the anchor. Renders a div element.

Styling
classNamestring | ((state) => string)

Class names applied to the rendered element.

styleReact.CSSProperties | ((state) => React.CSSProperties)

Inline styles applied to the rendered element.

Composition
renderReactElement | ((props, state) => ReactElement)

Custom render target while preserving Base UI behavior.

Arrow data attributes
AttributeDescription
data-openPresent when the popup is open.
data-closedPresent when the popup is closed.
data-sideIndicates the resolved popup side.
data-alignIndicates the resolved popup alignment.
data-uncenteredPresent when the arrow cannot be centered on the anchor.

Status

A polite live region for status text. Renders a div element and should stay mounted.

Styling
classNamestring | ((state) => string)

Class names applied to the rendered element.

styleReact.CSSProperties | ((state) => React.CSSProperties)

Inline styles applied to the rendered element.

Composition
renderReactElement | ((props, state) => ReactElement)

Custom render target while preserving Base UI behavior.

Empty

Renders its children when the filtered list is empty. Renders a div element.

Styling
classNamestring | ((state) => string)

Class names applied to the rendered element.

styleReact.CSSProperties | ((state) => React.CSSProperties)

Inline styles applied to the rendered element.

Composition
renderReactElement | ((props, state) => ReactElement)

Custom render target while preserving Base UI behavior.

List

Container for filtered items. Renders a div element.

Composition
childrenReact.ReactNode | ((item, index) => React.ReactNode)

Static content or an item render function.

renderReactElement | ((props, state) => ReactElement)

Custom render target while preserving Base UI behavior.

Styling
classNamestring | ((state) => string)

Class names applied to the rendered element.

styleReact.CSSProperties | ((state) => React.CSSProperties)

Inline styles applied to the rendered element.

List data attributes
AttributeDescription
data-emptyPresent when the list is empty.

Row

A row of items for grid mode. Renders a div element.

Styling
classNamestring | ((state) => string)

Class names applied to the rendered element.

styleReact.CSSProperties | ((state) => React.CSSProperties)

Inline styles applied to the rendered element.

Composition
renderReactElement | ((props, state) => ReactElement)

Custom render target while preserving Base UI behavior.

Item

An item in the autocomplete list. Renders a div element.

Behavior
valueany
=null

Unique value for this item.

indexnumber

Optional list index used to avoid DOM index lookup.

State
disabledboolean
=false

Disables the item.

Events
onClickMouseEventHandler

Called when the item is selected by pointer or keyboard.

Composition
childrenReact.ReactNode

Item content.

nativeButtonboolean
=true

When false, the part renders with non-native button semantics.

renderReactElement | ((props, state) => ReactElement)

Custom render target while preserving Base UI behavior.

Styling
classNamestring | ((state) => string)

Class names applied to the rendered element.

styleReact.CSSProperties | ((state) => React.CSSProperties)

Inline styles applied to the rendered element.

Item data attributes
AttributeDescription
data-highlightedPresent when the item is highlighted.
data-disabledPresent when the item is disabled.

Separator

Accessible separator between list sections. Renders a div element.

Behavior
orientation'horizontal' | 'vertical'
='horizontal'

Separator orientation.

Styling
classNamestring | ((state) => string)

Class names applied to the rendered element.

styleReact.CSSProperties | ((state) => React.CSSProperties)

Inline styles applied to the rendered element.

Composition
renderReactElement | ((props, state) => ReactElement)

Custom render target while preserving Base UI behavior.

Group

Groups related items with a label. Renders a div element.

Behavior
itemsreadonly Item[]

Items rendered by child Collection parts.

Styling
classNamestring | ((state) => string)

Class names applied to the rendered element.

styleReact.CSSProperties | ((state) => React.CSSProperties)

Inline styles applied to the rendered element.

Composition
renderReactElement | ((props, state) => ReactElement)

Custom render target while preserving Base UI behavior.

GroupLabel

Label for a grouped item section. Renders a div element.

Styling
classNamestring | ((state) => string)

Class names applied to the rendered element.

styleReact.CSSProperties | ((state) => React.CSSProperties)

Inline styles applied to the rendered element.

Composition
renderReactElement | ((props, state) => ReactElement)

Custom render target while preserving Base UI behavior.

Collection

Renders filtered items from the nearest Root or Group. It does not render an element.

Composition
children(item, index) => React.ReactNodeRequired

Render function for each filtered item.

useFilter

Base UI hook used to create locale-aware filters for controlled filtering.

Behavior
optionsAutocompleteFilterOptions

Filter options such as locale and sensitivity.

Return
returnsAutocompleteFilter

Filter function compatible with Root filter or external filtering.

useFilteredItems

Base UI hook used to filter flat or grouped item arrays outside Root.

Behavior
itemsreadonly Item[] | readonly Group[]

Items to filter.

filterAutocompleteFilter | null

Filter function to apply.

querystring

Current query value.

limitnumber
=-1

Maximum number of items to return.

Return
returnsreadonly Item[] | readonly Group[]

Filtered items for Root filteredItems.