Combobox
Enables users to pick from a list of options displayed in a dropdown.
Structure
API Reference
The root combobox component which manages & scopes the state of the combobox.
Property | Type | Description |
---|---|---|
type Required | enum | The type of combobox. Default: undefined |
value bindable prop | union | The value of the combobox. When the type is Default: undefined |
onValueChange | function | A callback that is fired when the combobox value changes. When the type is Default: undefined |
open bindable prop | boolean | The open state of the combobox menu. Default: false |
onOpenChange | function | A callback that is fired when the combobox menu's open state changes. Default: undefined |
disabled | boolean | Whether or not the combobox component is disabled. Default: false |
name | string | The name to apply to the hidden input element for form submission. If provided, a hidden input element will be rendered to submit the value of the combobox. Default: undefined |
required | boolean | Whether or not the combobox menu is required. Default: false |
scrollAlignment | enum | The alignment of the highlighted item when scrolling. Default: 'nearest' |
loop | boolean | Whether or not the combobox menu should loop through items. Default: false |
children | Snippet | The children content to render. Default: undefined |
The element which contains the combobox's items.
Property | Type | Description |
---|---|---|
side | enum | The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur. Default: bottom |
sideOffset | number | The distance in pixels from the anchor to the floating element. Default: 0 |
align | enum | The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur. Default: start |
alignOffset | number | The distance in pixels from the anchor to the floating element. Default: 0 |
arrowPadding | number | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision. Default: 0 |
avoidCollisions | boolean | When Default: true |
collisionBoundary | union | A boundary element or array of elements to check for collisions against. Default: undefined |
collisionPadding | union | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision. Default: 0 |
sticky | enum | The sticky behavior on the align axis. Default: partial |
hideWhenDetached | boolean | When Default: true |
updatePositionStrategy | enum | The strategy to use when updating the position of the content. When Default: optimized |
strategy | enum | The positioning strategy to use for the floating element. When Default: fixed |
preventScroll | boolean | When Default: true |
onEscapeKeydown | function | Callback fired when an escape keydown event occurs in the floating content. You can call Default: undefined |
escapeKeydownBehavior | enum | The behavior to use when an escape keydown event occurs in the floating content. Default: close |
onInteractOutside | function | Callback fired when an outside interaction event completes, which is either a Default: undefined |
onInteractOutsideStart | function | Callback fired when an outside interaction event starts, which is either a Default: undefined |
onFocusOutside | function | Callback fired when focus leaves the dismissable layer. You can call Default: undefined |
interactOutsideBehavior | enum | The behavior to use when an interaction occurs outside of the floating content. Default: close |
onMountAutoFocus | function | Event handler called when auto-focusing the content as it is mounted. Can be prevented. Default: undefined |
onDestroyAutoFocus | function | Event handler called when auto-focusing the content as it is destroyed. Can be prevented. Default: undefined |
preventOverflowTextSelection | boolean | When Default: true |
dir | enum | The reading direction of the app. Default: ltr |
loop | boolean | Whether or not the combobox should loop through items when reaching the end. Default: false |
forceMount | boolean | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animnation library for the content. Default: false |
child | Snippet | Use render delegation to render your own element. See render delegation for more information. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
ref | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-combobox-content | —— | Present on the content element. |
A combobox item, which must be a child of the Combobox.Content
component.
Property | Type | Description |
---|---|---|
value Required | string | The value of the item. Default: undefined |
label | string | The label of the item, which is what the list will be filtered by. Default: undefined |
disabled | boolean | Whether or not the combobox item is disabled. This will prevent interaction/selection. Default: false |
onHighlight | function | A callback that is fired when the item is highlighted. Default: undefined |
onUnhighlight | function | A callback that is fired when the item is unhighlighted. Default: undefined |
child | Snippet | Use render delegation to render your own element. See render delegation for more information. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
ref | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-state | enum | The state of the item. |
data-disabled | —— | Present when the item is disabled. |
data-highlighted | —— | Present when the item is highlighted, via keyboard navigation or hover. |
data-combobox-item | —— | Present on the item element. |
A representation of the combobox input element, which is typically displayed in the content.
Property | Type | Description |
---|---|---|
defaultValue | string | The default value of the input. This is not a reactive prop and is only used to populate the input when the combobox is first mounted if there is already a value set. Default: undefined |
child | Snippet | Use render delegation to render your own element. See render delegation for more information. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
ref | HTMLInputElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-combobox-input | —— | Present on the input element. |
A label for the combobox input element, which is typically displayed in the content.
Property | Type | Description |
---|---|---|
child | Snippet | Use render delegation to render your own element. See render delegation for more information. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
ref | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-combobox-label | —— | Present on the label element. |
An optional arrow element which points to the content when open.
Property | Type | Description |
---|---|---|
width | number | The width of the arrow in pixels. Default: 8 |
height | number | The height of the arrow in pixels. Default: 8 |
child | Snippet | Use render delegation to render your own element. See render delegation for more information. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
ref | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-arrow | —— | Present on the arrow element. |