Ark Logo
GitHub
Components
Select

Select

Displays a list of options for the user to pick from.

Anatomy

To set up the select correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Examples

Learn how to use the Select component in your project. Let's take a look at the most basic example:

<script setup lang="ts">
import { ref } from 'vue'
import { Select } from '@ark-ui/vue'
import { ChevronDownIcon } from 'lucide-vue-next'

const items = ref(['React', 'Solid', 'Vue'])
</script>

<template>
  <Select.Root :items="items">
    <Select.Label>Framework</Select.Label>
    <Select.Control>
      <Select.Trigger>
        <Select.ValueText placeholder="Select a Framework" />
        <Select.Indicator>
          <ChevronDownIcon />
        </Select.Indicator>
      </Select.Trigger>
      <Select.ClearTrigger>Clear</Select.ClearTrigger>
    </Select.Control>
    <Teleport to="body">
      <Select.Positioner>
        <Select.Content>
          <Select.ItemGroup>
            <Select.ItemGroupLabel>Frameworks</Select.ItemGroupLabel>
            <Select.Item v-for="item in items" :key="item" :item="item">
              <Select.ItemText>{{ item }}</Select.ItemText>
              <Select.ItemIndicator>✓</Select.ItemIndicator>
            </Select.Item>
          </Select.ItemGroup>
        </Select.Content>
      </Select.Positioner>
    </Teleport>
    <Select.HiddenSelect />
  </Select.Root>
</template>

Advanced Customization

For advanced customizations and item properties like disabled:

<script setup lang="ts">
import { ref } from 'vue'
import { Select } from '@ark-ui/vue'
import { ChevronDownIcon } from 'lucide-vue-next'

const items = ref([
  { label: 'React', value: 'react' },
  { label: 'Solid', value: 'solid' },
  { label: 'Vue', value: 'vue' },
  { label: 'Svelte', value: 'svelte', disabled: true },
])
</script>

<template>
  <Select.Root :items="items">
    <Select.Label>Framework</Select.Label>
    <Select.Control>
      <Select.Trigger>
        <Select.ValueText placeholder="Select a Framework" />
        <Select.Indicator>
          <ChevronDownIcon />
        </Select.Indicator>
      </Select.Trigger>
      <Select.ClearTrigger>Clear</Select.ClearTrigger>
    </Select.Control>
    <Teleport to="body">
      <Select.Positioner>
        <Select.Content>
          <Select.ItemGroup>
            <Select.ItemGroupLabel>Frameworks</Select.ItemGroupLabel>
            <Select.Item v-for="item in items" :key="item.value" :item="item">
              <Select.ItemText>{{ item.label }}</Select.ItemText>
              <Select.ItemIndicator>✓</Select.ItemIndicator>
            </Select.Item>
          </Select.ItemGroup>
        </Select.Content>
      </Select.Positioner>
    </Teleport>
    <Select.HiddenSelect />
  </Select.Root>
</template>

Multiple Selection

To enable multiple item selection:

<script setup lang="ts">
import { ref } from 'vue'
import { Select } from '@ark-ui/vue'

const items = ref([
  { label: 'React', value: 'react' },
  { label: 'Solid', value: 'solid' },
  { label: 'Vue', value: 'vue' },
  { label: 'Svelte', value: 'svelte', disabled: true },
])
</script>

<template>
  <Select.Root :items="items" multiple>
    <Select.Label>Framework</Select.Label>
    <Select.Control>
      <Select.Trigger>
        <Select.ValueText placeholder="Select a Framework" />
        <Select.Indicator>
          <ChevronDownIcon />
        </Select.Indicator>
      </Select.Trigger>
      <Select.ClearTrigger>Clear</Select.ClearTrigger>
    </Select.Control>
    <Teleport to="body">
      <Select.Positioner>
        <Select.Content>
          <Select.ItemGroup>
            <Select.ItemGroupLabel>Frameworks</Select.ItemGroupLabel>
            <Select.Item v-for="item in items" :key="item.value" :item="item">
              <Select.ItemText>{{ item.label }}</Select.ItemText>
              <Select.ItemIndicator>✓</Select.ItemIndicator>
            </Select.Item>
          </Select.ItemGroup>
        </Select.Content>
      </Select.Positioner>
    </Teleport>
    <Select.HiddenSelect />
  </Select.Root>
</template>

Controlled Component

For scenarios where you want to control the Select component's state:

<script setup lang="ts">
import { ref } from 'vue'
import { Select } from '@ark-ui/vue'
import { ChevronDownIcon } from 'lucide-vue-next'

const items = ref([
  { label: 'React', value: 'react' },
  { label: 'Solid', value: 'solid' },
  { label: 'Vue', value: 'vue' },
  { label: 'Svelte', value: 'svelte', disabled: true },
])

const value = ref(['vue'])
</script>

<template>
  <Select.Root :items="items" v-model="value">
    <Select.Label>Framework</Select.Label>
    <Select.Control>
      <Select.Trigger>
        <Select.ValueText placeholder="Select a Framework" />
        <Select.Indicator>
          <ChevronDownIcon />
        </Select.Indicator>
      </Select.Trigger>
      <Select.ClearTrigger>Clear</Select.ClearTrigger>
    </Select.Control>
    <Teleport to="body">
      <Select.Positioner>
        <Select.Content>
          <Select.ItemGroup>
            <Select.ItemGroupLabel>Frameworks</Select.ItemGroupLabel>
            <Select.Item v-for="item in items" :key="item.value" :item="item">
              <Select.ItemText>{{ item.label }}</Select.ItemText>
              <Select.ItemIndicator>✓</Select.ItemIndicator>
            </Select.Item>
          </Select.ItemGroup>
        </Select.Content>
      </Select.Positioner>
    </Teleport>
    <Select.HiddenSelect />
  </Select.Root>
</template>

Usage with a Form Library

See how to use the Select component with popular form libraries:

Example not found

Using the Field Component

The Field component helps manage form-related state and accessibility attributes of a select. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility.

<script setup lang="ts">
import { ref } from 'vue'
import { Field, Select } from '@ark-ui/vue'
import { ChevronDownIcon } from 'lucide-vue-next'

const items = ref(['React', 'Solid', 'Vue'])
</script>

<template>
  <Field.Root>
    <Select.Root :items="items">
      <Select.Label>Label</Select.Label>
      <Select.Control>
        <Select.Trigger>
          <Select.ValueText placeholder="Select a Framework" />
          <Select.Indicator>
            <ChevronDownIcon />
          </Select.Indicator>
        </Select.Trigger>
        <Select.ClearTrigger>Clear</Select.ClearTrigger>
      </Select.Control>
      <Teleport to="body">
        <Select.Positioner>
          <Select.Content>
            <Select.ItemGroup>
              <Select.ItemGroupLabel>Frameworks</Select.ItemGroupLabel>
              <Select.Item v-for="item in items" :key="item" :item="item">
                <Select.ItemText>{{ item }}</Select.ItemText>
                <Select.ItemIndicator>✓</Select.ItemIndicator>
              </Select.Item>
            </Select.ItemGroup>
          </Select.Content>
        </Select.Positioner>
      </Teleport>
      <Select.HiddenSelect />
    </Select.Root>
    <Field.HelperText>Additional Info</Field.HelperText>
    <Field.ErrorText>Error Info</Field.ErrorText>
  </Field.Root>
</template>

API Reference

Root

PropDefaultType
items
T[] | readonly T[]

The options of the select

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
closeOnSelecttrue
boolean

Whether the select should close after an item is selected

compositetrue
boolean

Whether the select is a composed with other composite widgets like tabs or combobox

defaultOpen
boolean

The initial open state of the select when it is first rendered. Use when you do not need to control its open state.

defaultValue
string[]

The initial value of the select when it is first rendered. Use when you do not need to control the state of the select.

disabled
boolean

Whether the select is disabled

form
string

The associate form of the underlying select.

highlightedValue
string

The 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

isItemDisabled
(item: T) => boolean

Whether the item is disabled

itemToString
(item: T) => string

The label of the item

itemToValue
(item: T) => string

The value of the item

lazyMountfalse
boolean

Whether to enable lazy mounting

loopFocusfalse
boolean

Whether to loop the keyboard navigation through the options

modelValue
string[]

multiple
boolean

Whether to allow multiple selection

name
string

The `name` attribute of the underlying select.

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

unmountOnExitfalse
boolean

Whether to unmount on exit.

Data AttributeValue
[data-scope]select
[data-part]root
[data-invalid]Present when invalid
[data-readonly]Present when read-only

ClearTrigger

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Content

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]select
[data-part]content
[data-state]"open" | "closed"
[data-placement]The placement of the content
[data-activedescendant]

Control

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]select
[data-part]control
[data-state]"open" | "closed"
[data-focus]Present when focused
[data-disabled]Present when disabled
[data-invalid]Present when invalid

HiddenSelect

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Indicator

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]select
[data-part]indicator
[data-state]"open" | "closed"
[data-disabled]Present when disabled
[data-invalid]Present when invalid
[data-readonly]Present when read-only

ItemGroupLabel

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

ItemGroup

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
id
string

Data AttributeValue
[data-scope]select
[data-part]item-group
[data-disabled]Present when disabled

ItemIndicator

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]select
[data-part]item-indicator
[data-state]"checked" | "unchecked"

Item

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
item
any

The item to render

persistFocus
boolean

Whether hovering outside should clear the highlighted state

Data AttributeValue
[data-scope]select
[data-part]item
[data-value]
[data-state]"checked" | "unchecked"
[data-highlighted]Present when highlighted
[data-disabled]Present when disabled

ItemText

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]select
[data-part]item-text
[data-disabled]Present when disabled
[data-highlighted]Present when highlighted

Label

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]select
[data-part]label
[data-disabled]Present when disabled
[data-invalid]Present when invalid
[data-readonly]Present when read-only

List

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Positioner

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

RootProvider

PropDefaultType
value
MachineApi<PropTypes, T>

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
lazyMountfalse
boolean

Whether to enable lazy mounting

unmountOnExitfalse
boolean

Whether to unmount on exit.

Trigger

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]select
[data-part]trigger
[data-state]"open" | "closed"
[data-disabled]Present when disabled
[data-invalid]Present when invalid
[data-readonly]Present when read-only
[data-placement]The placement of the trigger
[data-placeholder-shown]Present when placeholder is shown

ValueText

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
placeholder
string

Accessibility

Complies with the Listbox WAI-ARIA design pattern.

Keyboard Support

KeyDescription
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-Za-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.