Select · base-ui-svelte

`readOnly`

readOnly locks the value, not the interaction. The popup still opens for browsing; item presses, Enter-to-select, and closed-trigger typeahead commits stay blocked.

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.

Select.Root

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

Props

value SelectValue —

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

defaultValue SelectValue —

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

onValueChange function —

Name: onValueChange
Description: Event handler called when the value changes.
Type: ((value: SelectValue, 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

disabled boolean false

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

name string —

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

multiple boolean false

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

modal boolean true

Name: modal
Description: Whether the select enters a modal state when open. When true, document scroll is locked while open.
Type: boolean
Default: true

onOpenChangeComplete function —

Name: onOpenChangeComplete
Description: Event handler called after any animations complete when the select popup is opened or closed.
Type: ((open: boolean) => void) | undefined

form string —

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

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 and typeahead commits stay 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

autoComplete HTMLInputAttributes['auto… —

Name: autoComplete
Description: Provides a hint to the browser for autofill.
Type: HTMLInputAttributes['autocomplete']

highlightItemOnHover boolean true

Name: highlightItemOnHover
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: boolean
Default: true

itemToStringLabel function —

Name: itemToStringLabel
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: ((itemValue: string) => string) | undefined

itemToStringValue function —

Name: itemToStringValue
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: ((itemValue: string) => string) | undefined

isItemEqualToValue function —

Name: isItemEqualToValue
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: ((itemValue: string, value: string) => boolean) | undefined

items SelectItemsProp —

Name: items
Description: Data structure of the items rendered in the select popup. When specified, <Select.Value> renders the label of the selected item instead of the raw value.
Type: SelectItemsProp | undefined

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet<[{ value: SelectValue; 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.

Select.Arrow

Displays an element positioned against the select popup 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 select popup is closed.
`data-open`	Present when the select popup is open.

Select.Backdrop

An overlay displayed beneath the select 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 select is closed.
`data-open`	Present when the select is open.

Select.Group

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

Props

children snippet —

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

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

Select.Icon

An icon that indicates that the trigger button opens a select 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.

Select.Item

An individual option in the select popup. Renders a <div> element.

Props

value string null

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

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 select item is disabled.
`data-highlighted`	Present when the select item is highlighted.
`data-selected`	Present when the select item is selected.

Select.ItemIndicator

Indicates whether the select 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.

Select.ItemText

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

Props

children snippet —

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

Data attributes

Attribute	Description
`data-highlighted`	Present when the item is highlighted.
`data-select-item-text`	Present on the element when applicable.
`data-selected`	Present when the item is selected.

Select.Label

An accessible label that is automatically associated with the select 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.

Select.List

A container for the select 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.

Select.Popup

A container for the select list. 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 select is closed.
`data-ending-style`	Present when the select is animating out.
`data-open`	Present when the select is open.
`data-starting-style`	Present when the select begins animating in.

Select.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 —

Name: keepMounted
Description: —
Type: boolean

children snippet —

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

Select.Positioner

Positions the select popup. Renders a <div> element.

Props

side { t 'bottom'

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

align LElem 'center'

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

sideOffset up: HT 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: up: HT
Default: 0

alignOffset posi 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: posi
Default: 0

collisionPadding null; list: HTMLElement | null; arro 5

Name: collisionPadding
Description: Additional space to maintain from the edge of the collision boundary.
Type: null; list: HTMLElement | null; arro
Default: 5

collisionBoundary }; export type 'clipping-ancestors'

Name: collisionBoundary
Description: An element or a rectangle that delimits the area that the popup is confined to.
Type: }; export type
Default: 'clipping-ancestors'

collisionAvoidance only value: Select —

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: only value: Select

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

sticky event: false

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

positionMethod eReason): void; r 'absolute'

Name: positionMethod
Description: Maps to Floating UI strategy (absolute | fixed).
Type: eReason): void; r
Default: 'absolute'

strategy string —

Name: strategy
Description: —
Type: ing, label: string

anchor l): void; readonly items:… —

Name: anchor
Description: Override the positioning anchor (element or virtual element).
Type: l): void; readonly items: Sele

disableAnchorTracking string 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: string
Default: false

alignItemWithTrigger boolean true

Name: alignItemWithTrigger
Description: Whether the positioner overlaps the trigger so the selected item's text is aligned with the trigger's value text. This only applies to mouse input and is automatically disabled if there is not enough space.
Type: boolean
Default: true

children snippet —

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

Data attributes

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

Select.ScrollDownArrow

An element that scrolls the select popup down when hovered. Does not render when using touch input. Renders a <div> element.

Props

children snippet —

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

Data attributes

Attribute	Description
`data-direction`	Indicates the direction of the scroll arrow.
`data-hidden`	Present on the element when applicable.

Select.ScrollUpArrow

An element that scrolls the select popup up when hovered. Does not render when using touch input. Renders a <div> element.

Props

children snippet —

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

Data attributes

Attribute	Description
`data-direction`	Indicates the direction of the scroll arrow.
`data-hidden`	Present on the element when applicable.

Select.Separator

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

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

Select.Trigger

A button that opens the select 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 select is disabled.
`data-open`	Present when the part is open.
`data-readonly`	Present when the select is readonly.

Select.Value

A text label of the currently selected item. Renders a <span> 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<[SelectValue]>

Data attributes

Attribute	Description
`data-placeholder`	Present when the select doesn't have a value.