Combobox · base-ui-svelte

`createItems`

Use Combobox.createItems() when selection should store a primitive ID while the list still renders from richer source objects:

const items = Combobox.createItems(users, {
	getValue: (user) => user.id,
	getLabel: (user) => user.name
});

// <Combobox.Root {items}>…

Pass the collection to items. Labels resolve via getLabel for values present in the collection; use itemToStringLabel as a fallback for values outside the current data set.

`readOnly` and preserving filter text

readOnly locks the value, not the interaction — the popup still opens for browsing.

To keep the filter after a multi-select item press:

onInputChange={(_value, eventDetails) => {
	if (eventDetails.isItemPress) {
		eventDetails.cancel();
	}
}}

API Reference

Props mirror Base UI React where applicable, adapted for Svelte 5. Native HTML attributes for the rendered element are also accepted unless noted.

Combobox.Root

Groups all parts of the combobox. Doesn't render its own HTML element.

Props

value ComboboxValue —

Name: value
Description: Controlled value.
Type: ComboboxValue | undefined

defaultValue ComboboxValue —

Name: defaultValue
Description: Uncontrolled initial value.
Type: ComboboxValue

onValueChange function —

Name: onValueChange
Description: Event handler called when the value changes.
Type: ((value: ComboboxValue, event: Event) => void) | undefined

inputValue string —

Name: inputValue
Description: The input value of the combobox. Use when controlled.
Type: string | undefined

defaultInputValue string —

Name: defaultInputValue
Description: The uncontrolled input value when initially rendered. To render a controlled input, use the inputValue prop instead.
Type: string

onInputChange function —

Name: onInputChange
Description: Called when the input value changes. Use eventDetails.cancel() to keep the previous value (e.g. preserve filter text after a multi-select item press when eventDetails.isItemPress is true).
Type: | ((value: string, eventDetails: ComboboxInputChangeEventDetails, event?: Event) => void) | undefined

open boolean —

Name: open
Description: Whether the component is open (controlled).
Type: boolean | undefined

defaultOpen boolean false

Name: defaultOpen
Description: Whether the component is initially open (uncontrolled).
Type: boolean
Default: false

onOpenChange function —

Name: onOpenChange
Description: Event handler called when the open state changes.
Type: ((open: boolean, eventDetails: { reason: OpenChangeReason }) => void) | undefined

onOpenChangeComplete function —

Name: onOpenChangeComplete
Description: Called after open/close animations complete.
Type: ((open: boolean) => void) | undefined

disabled boolean false

Name: disabled
Description: Whether the control ignores user interaction.
Type: boolean
Default: false

readOnly boolean false

Name: readOnly
Description: Whether the user should be unable to choose a different option. The popup can still open and be browsed; selection stays blocked.
Type: boolean
Default: false

required boolean false

Name: required
Description: Whether the user must choose a value before submitting a form.
Type: boolean
Default: false

name string —

Name: name
Description: Identifies the field when a form is submitted.
Type: string | undefined

form string —

Name: form
Description: Identifies the form that owns the internal input. Useful when the combobox is rendered outside the form.
Type: string | undefined

filter ComboboxFilter —

Name: filter
Description: ComboboxFilter function used to match items vs input query.
Type: ComboboxFilter

filteredItems string —

Name: filteredItems
Description: Externally filtered item values; when set, skips internal filtering.
Type: ReadonlyArray<string> | undefined

limit number -1

Name: limit
Description: Max visible items (-1 = no limit).
Type: number
Default: -1

locale string —

Name: locale
Description: Locale for default string filtering.
Type: string | undefined

autoHighlight boolean false

Name: autoHighlight
Description: Highlight the first matching item while filtering.
Type: boolean
Default: false

highlightItemOnHover boolean true

Name: highlightItemOnHover
Description: Highlight items on pointer move.
Type: boolean
Default: true

onItemHighlighted function —

Name: onItemHighlighted
Description: Callback fired when an item is highlighted or unhighlighted.
Receives the highlighted item value (or undefined if no item is highlighted) and event details with a reason property describing why the highlight changed.
The reason can be: 'keyboard': the highlight changed due to keyboard navigation.
'pointer': the highlight changed due to pointer hovering.
'none': the highlight changed programmatically.
Type: | ((value: string | null, eventDetails: { reason: 'none' | 'keyboard' | 'pointer' | 'filter' }) => void) | undefined

itemToStringLabel function —

Name: itemToStringLabel
Description: When the item values are objects (<Combobox.Item value={object}>), this function converts the object value to a string representation for display in the input. If the shape of the object is { value, label }, the label will be used automatically without needing to specify this prop.
Type: ((itemValue: string) => string) | undefined

itemToStringValue function —

Name: itemToStringValue
Description: When the item values are objects (<Combobox.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: ((itemValue: string) => string) | undefined

isItemEqualToValue function —

Name: isItemEqualToValue
Description: Custom comparison logic used to determine if a combobox item value matches the current selected value. Useful when item values are objects without matching referentially. Defaults to Object.is comparison.
Type: ((itemValue: string, value: string) => boolean) | undefined

multiple boolean false

Name: multiple
Description: Whether multiple items can be selected.
Type: boolean
Default: false

loopFocus boolean true

Name: loopFocus
Description: Whether highlight wraps at list ends.
Type: boolean
Default: true

modal boolean false

Name: modal
Description: Whether the popup behaves as a modal layer.
Type: boolean
Default: false

openOnInputClick boolean true

Name: openOnInputClick
Description: Open the popup when the input is clicked.
Type: boolean
Default: true

items ComboboxItemsProp —

Name: items
Description: The items to be displayed in the list. Can be either a flat array of items or an array of groups with items.
Type: ComboboxItemsProp | undefined

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet< [{ value: ComboboxValue; inputValue: string; open: boolean; disabled: boolean }] >

Data attributes

Attribute	Description
`data-closed`	Present when the part is closed.
`data-disabled`	Present when the part is disabled.
`data-open`	Present when the part is open.
`data-readonly`	Present when the control is read-only.

Combobox.Arrow

Displays an element positioned against the anchor. Renders a <div> element.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-closed`	Present when the popup is closed.
`data-open`	Present when the popup is open.

Combobox.Backdrop

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

Props

render string —

Name: render
Description: HTML element tag to render instead of the default host element.
Type: string

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-closed`	Present when the popup is closed.
`data-open`	Present when the popup is open.

Combobox.Chip

An individual chip that represents a value in a multiselectable input. Renders a <div> element.

Props

value string —

Name: value
Description: Controlled value.
Type: string

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-disabled`	Present when the part is disabled.

Combobox.ChipRemove

A button to remove a chip. Renders a <button> element.

Props

disabled boolean false

Name: disabled
Description: Whether the control ignores user interaction.
Type: boolean
Default: false

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-disabled`	Present when the part is disabled.

Combobox.Chips

A container for the chips in a multiselectable input. Renders a <div> element.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Combobox.Clear

Clears the value when clicked. Renders a <button> element.

Props

disabled boolean false

Name: disabled
Description: Whether the control ignores user interaction.
Type: boolean
Default: false

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-disabled`	Present when the button is disabled.
`data-empty`	Present on the element when applicable.
`data-hidden`	Present on the element when applicable.

Combobox.Collection

Renders filtered list items. 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.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet<[ComboboxCollectionItem]>

Renders its children only when the list is empty. Requires the items prop on the root component. Announces changes politely to screen readers. This component's root element must remain mounted in the DOM to announce changes consistently across screen readers. Avoid hiding or removing the component itself with display: none, hidden, aria-hidden, or conditional rendering. Prefer updating or conditionally rendering its children instead. Renders a <div> element.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-empty`	Present on the element when applicable.

Combobox.Group

Groups related items with the corresponding label. Renders a <div> element.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Combobox.GroupLabel

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

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Combobox.Icon

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

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-closed`	Present when the part is closed.
`data-open`	Present when the part is open.

Combobox.Input

A text input to search for items in the list. Renders an <input> element.

Props

disabled boolean false

Name: disabled
Description: Whether the control ignores user interaction.
Type: boolean
Default: false

Data attributes

Attribute	Description
`data-closed`	Present when the part is closed.
`data-disabled`	Present when the component is disabled.
`data-open`	Present when the part is open.
`data-readonly`	Present when the component is readonly.

Combobox.InputGroup

A wrapper for the input and its associated controls. Renders a <div> element.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-closed`	Present when the part is closed.
`data-disabled`	Present when the component is disabled.
`data-open`	Present when the part is open.

Combobox.Item

An individual item in the list. Renders a <div> element.

Props

value string null

Name: value
Description: Controlled value.
Type: string
Default: null

label string —

Name: label
Description: —
Type: string

disabled boolean false

Name: disabled
Description: Whether the control ignores user interaction.
Type: boolean
Default: false

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet<[{ selected: boolean; highlighted: boolean; disabled: boolean }]>

Data attributes

Attribute	Description
`data-disabled`	Present when the item is disabled.
`data-highlighted`	Present when the item is highlighted.
`data-selected`	Present when the item is selected.

Combobox.ItemIndicator

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

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-disabled`	Present when the part is disabled.
`data-selected`	Present when the item is selected.

Combobox.Label

An accessible label that is automatically associated with the combobox trigger. Renders a <div> element.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-disabled`	Present when the part is disabled.

Combobox.List

A list container for the items. Renders a <div> element.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-closed`	Present when the part is closed.
`data-open`	Present when the part is open.

Combobox.Popup

A container for the list. Renders a <div> element.

Props

render string —

Name: render
Description: HTML element tag to render instead of the default host element.
Type: string

initialFocus FocusTarget —

Name: initialFocus
Description: Determines the element to focus when the popup is opened. false: Do not move focus.true: Move focus based on the default behavior (first tabbable element or popup).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: FocusTarget

finalFocus FocusTarget —

Name: finalFocus
Description: Determines the element to focus when the 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: FocusTarget

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-closed`	Present when the popup is closed.
`data-ending-style`	Present when the popup is animating out.
`data-open`	Present when the popup is open.
`data-starting-style`	Present when the popup begins animating in.

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

Props

container HTMLElement | string | null —

Name: container
Description: A parent element to render the portal element into.
Type: HTMLElement | string | null

keepMounted boolean false

Name: keepMounted
Description: Whether to keep the portal mounted in the DOM while the popup is hidden.
Type: boolean
Default: false

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Combobox.Positioner

Positions the popup against the trigger. Renders a <div> element.

Props

side type 'bottom'

Name: side
Description: Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
Type: type
Default: 'bottom'

align lter 'center'

Name: align
Description: How to align the popup relative to the specified side.
Type: lter
Default: 'center'

sideOffset ((item 0

Name: sideOffset
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: ((item
Default: 0

alignOffset ery: s 0

Name: alignOffset
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: ery: s
Default: 0

collisionPadding boolean 5

Name: collisionPadding
Description: Additional space to maintain from the edge of the collision boundary.
Type: ng) => boolean); export type Combobox
Default: 5

collisionBoundary object 'clipping-ancestors'

Name: collisionBoundary
Description: An element or a rectangle that delimits the area that the popup is confined to.
Type: Array<{ read
Default: 'clipping-ancestors'

collisionAvoidance eadonly label?: st —

Name: collisionAvoidance
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: eadonly label?: st

arrowPadding boboxI 5

Name: arrowPadding
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: boboxI
Default: 5

sticky n; exp false

Name: sticky
Description: Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.
Type: n; exp
Default: false

positionMethod string 'absolute'

Name: positionMethod
Description: Maps to Floating UI strategy (absolute | fixed).
Type: bel: string; read
Default: 'absolute'

strategy HTMLElement | null —

Name: strategy
Description: —
Type: HTMLElement | null

anchor | null; arrow: HTMLElement | n —

Name: anchor
Description: Override the positioning anchor (element or virtual element).
Type: | null; arrow: HTMLElement | n

disableAnchorTracking Event, false

Name: disableAnchorTracking
Description: When true, skip continuous layout tracking of the anchor (position once; no resize/scroll auto-updates beyond the initial compute).
Type: Event,
Default: false

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-closed`	Present when the popup is closed.
`data-open`	Present when the popup is open.

Combobox.Row

Displays a single row of items in a grid list. Enable grid on the root component to turn the listbox into a grid. Renders a <div> element.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Combobox.Separator

A visual separator between items or groups. Renders a <div> element.

No component-specific props — HTML attributes and children only.

Combobox.Status

Displays a status message whose content changes are announced politely to screen readers. Useful for conveying the status of an asynchronously loaded list. This component's root element must remain mounted in the DOM to announce changes consistently across screen readers. Avoid hiding or removing the component itself with display: none, hidden, aria-hidden, or conditional rendering. Prefer updating or conditionally rendering its children instead. Renders a <div> element.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-closed`	Present when the part is closed.
`data-open`	Present when the part is open.

Combobox.Trigger

A button that opens the popup. Renders a <button> element.

Props

render string —

Name: render
Description: HTML element tag to render instead of the default host element.
Type: string

disabled boolean false

Name: disabled
Description: Whether the control ignores user interaction.
Type: boolean
Default: false

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-closed`	Present when the part is closed.
`data-disabled`	Present when the component is disabled.
`data-open`	Present when the part is open.
`data-readonly`	Present when the component is readonly.

Combobox.Value

The current value of the combobox. Doesn't render its own HTML element.

Props

placeholder string —

Name: placeholder
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: string

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet<[ComboboxValue]>

Data attributes

Attribute	Description
`data-placeholder`	Present when showing placeholder content.

createItems

readOnly and preserving filter text

API Reference

`createItems`

`readOnly` and preserving filter text