Select

A component for choosing an option from a dropdown list.

Label

Anatomy

Usage

<script>
  import {Select} from 'ui-ingredients';
  import {CheckIcon, ChevronDownIcon} from '$lib/icons';

  let collection = Select.collection({
    items: [
      {value: '1', label: 'Option 1'},
      {value: '2', label: 'Option 2'},
      {value: '3', label: 'Option 3'},
      {value: '4', label: 'Option 4'},
      {value: '5', label: 'Option 5'},
    ],
  });
</script>

<Select.Root {collection}>
  <Select.Control>
    <Select.Label>Label</Select.Label>
    <Select.Trigger>
      <ChevronDownIcon />
    </Select.Trigger>
  </Select.Control>

  <Select.Positioner>
    <Select.Content>
      {#each collection.items as item}
        <Select.Item {item}>
          <Select.ItemText />
          <Select.ItemIndicator>
            <CheckIcon />
          </Select.ItemIndicator>
        </Select.Item>
      {/each}
    </Select.Content>
  </Select.Positioner>
</Select.Root>

Usage with Field component

<script>
  import {Select} from 'ui-ingredients';
  import {CheckIcon, ChevronDownIcon} from '$lib/icons';

  let collection = Select.collection({
    items: [
      {value: '1', label: 'Option 1'},
      {value: '2', label: 'Option 2'},
      {value: '3', label: 'Option 3'},
      {value: '4', label: 'Option 4'},
      {value: '5', label: 'Option 5'},
    ],
  });
</script>

<Field.Root>
  <Select.Root {collection}>
    <Select.Control>
      <Select.Label>Label</Select.Label>
      <Select.Trigger>
        <ChevronDownIcon />
      </Select.Trigger>
    </Select.Control>

    <Select.Positioner>
      <Select.Content>
        {#each items as item}
          <Select.Item {item}>
            <Select.ItemText />
            <Select.ItemIndicator>
              <CheckIcon />
            </Select.ItemIndicator>
          </Select.Item>
        {/each}
      </Select.Content>
    </Select.Positioner>
  </Select.Root>

  <Field.HelperText>This is a helper text</Field.HelperText>
  <Field.ErrorText>This is an error text</Field.ErrorText>
</Field.Root>

API Reference

Root

Prop	Default	Description
`closeOnSelect`	`true`	`boolean` Whether the select should close after an item is selected
`collection`		`ListCollection<T>` The item collection
`composite`	`true`	`boolean` Whether the select is a composed with other composite widgets like tabs or combobox
`defaultHighlightedValue`		`string` The initial value of the highlighted item when opened. Use when you don't need to control the highlighted value of the select.
`defaultOpen`		`boolean` Whether the select's open state is controlled by the user
`defaultValue`		`string[]` The initial default value of the select when rendered. Use when you don't need to control the value of the select.
`deselectable`		`boolean` Whether the value can be cleared by clicking the selected item. Note: this is only applicable for single selection
`disabled`		`boolean` Whether the select is disabled
`form`		`string` The associate form of the underlying select.
`highlightedValue`		`string` The controlled key of the highlighted item
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ root: string; content: string; control: string; trigger: string; clearTrigger: string; label: string; hiddenSelect: string; positioner: string; item(id: string \| number): string; itemGroup(id: string \| number): string; itemGroupLabel(id: string \| number): string; }>` The ids of the elements in the select. Useful for composition.
`invalid`		`boolean` Whether the select is invalid
`keepMounted`		`boolean` Whether to keep the component mounted after exit.
`lazyMount`		`boolean` Whether to enable lazy mounting.
`loopFocus`	`false`	`boolean` Whether to loop the keyboard navigation through the options
`multiple`		`boolean` Whether to allow multiple selection
`name`		`string` The `name` attribute of the underlying select.
`onFocusOutside`		`(event: FocusOutsideEvent) => void` Function called when the focus is moved outside the component
`onHighlightChange`		`(details: HighlightChangeDetails<T>) => void` The callback fired when the highlighted item changes.
`onInteractOutside`		`(event: InteractOutsideEvent) => void` Function called when an interaction happens outside the component
`onOpenChange`		`(details: OpenChangeDetails) => void` Function called when the popup is opened
`onPointerDownOutside`		`(event: PointerDownOutsideEvent) => void` Function called when the pointer is pressed down outside the component
`onValueChange`		`(details: ValueChangeDetails<T>) => void` The callback fired when the selected item changes.
`open`		`boolean` Whether the select menu is open
`positioning`		`PositioningOptions` The positioning options of the menu.
`readOnly`		`boolean` Whether the select is read-only
`required`		`boolean` Whether the select is required
`scrollToIndexFn`		`(details: ScrollToIndexDetails) => void` Function to scroll to a specific index
`value`		`string[]` The controlled keys of the selected items
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-invalid`	Present when invalid
`data-part`	root
`data-readonly`	Present when read-only
`data-scope`	select

ClearTrigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-invalid`	Present when invalid
`data-part`	clear-trigger
`data-scope`	select

Content

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-activedescendant`
`data-part`	content
`data-placement`	The placement of the content
`data-scope`	select
`data-state`	"open" \| "closed"

Control

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-focus`	Present when focused
`data-invalid`	Present when invalid
`data-part`	control
`data-scope`	select
`data-state`	"open" \| "closed"

Indicator

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid
`data-part`	indicator
`data-readonly`	Present when read-only
`data-scope`	select
`data-state`	"open" \| "closed"

Item

Prop	Default	Description
`item`		`any` The item data.
`persistFocus`		`boolean` Whether hovering outside should clear the highlighted state.
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-highlighted`	Present when highlighted
`data-part`	item
`data-scope`	select
`data-state`	"checked" \| "unchecked"
`data-value`	The value of the item

ItemGroup

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-part`	item-group
`data-scope`	select

ItemGroupLabel

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

ItemIndicator

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-part`	item-indicator
`data-scope`	select
`data-state`	"checked" \| "unchecked"

ItemText

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-highlighted`	Present when highlighted
`data-part`	item-text
`data-scope`	select
`data-state`	"checked" \| "unchecked"

Label

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid
`data-part`	label
`data-readonly`	Present when read-only
`data-scope`	select

List

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Positioner

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Trigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid
`data-part`	trigger
`data-placeholder-shown`	Present when placeholder is shown
`data-placement`	The placement of the trigger
`data-readonly`	Present when read-only
`data-scope`	select
`data-state`	"open" \| "closed"

ValueText

Prop	Default	Description
`placeholder`		`string` The placeholder text to display when no value is selected.
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-focus`	Present when focused
`data-invalid`	Present when invalid
`data-part`	value-text
`data-scope`	select

Accessibility

Keyboard Support

Key	Description
Space	When focus is on trigger, opens the select and focuses the first selected item. When focus is on the content, selects the highlighted item.
Enter	When focus is on trigger, opens the select and focuses the first selected item. When focus is on content, selects the focused item.
ArrowDown	When focus is on trigger, opens the select. When focus is on content, moves focus to the next item.
ArrowUp	When focus is on trigger, opens the select. When focus is on content, moves focus to the previous item.
Esc	Closes the select and moves focus to trigger.
A-Z + a-z	When focus is on trigger, selects the item whose label starts with the typed character. When focus is on the listbox, moves focus to the next item with a label that starts with the typed character.