Select

Select shows the chosen option in a pill and the options in a popup. It is built on Ark UI’s Select, so it has full keyboard support and typeahead.

import { Select } from '@beyul/sulmu-ui'

Source · Figma

Examples

Basic

value and defaultValue are arrays of option values, even for a single selection: defaultValue={['low']}.

import { Select } from '@beyul/sulmu-ui'

const priorities = [
  { value: 'low', label: 'Low' },
  { value: 'medium', label: 'Medium' },
  { value: 'high', label: 'High' },
  { value: 'urgent', label: 'Urgent', disabled: true },
]

export default function Example() {
  return (
    <div style={{ maxWidth: 320 }}>
      <Select aria-label="Priority" items={priorities} defaultValue={['low']} />
    </div>
  )
}

Multiple

import { Select } from '@beyul/sulmu-ui'

const priorities = [
  { value: 'low', label: 'Low' },
  { value: 'medium', label: 'Medium' },
  { value: 'high', label: 'High' },
]

export default function Example() {
  return (
    <div style={{ maxWidth: 320 }}>
      <Select aria-label="Priority" items={priorities} multiple defaultValue={['low', 'high']} />
    </div>
  )
}

Sizes and disabled

import { Select, Stack } from '@beyul/sulmu-ui'

const priorities = [
  { value: 'low', label: 'Low' },
  { value: 'medium', label: 'Medium' },
  { value: 'high', label: 'High' },
]

export default function Example() {
  return (
    <Stack style={{ maxWidth: 320 }}>
      <Select aria-label="Small" size="sm" items={priorities} placeholder="Small, 34px" />
      <Select aria-label="Medium" items={priorities} placeholder="Medium, 40px" />
      <Select aria-label="Large" size="lg" items={priorities} placeholder="Large, 44px" />
      <Select aria-label="Disabled" items={priorities} disabled defaultValue={['high']} />
    </Stack>
  )
}

Inside a Field, controlled

Choose a priority

import { Field, Select, Stack } from '@beyul/sulmu-ui'
import { useState } from 'react'

const priorities = [
  { value: 'low', label: 'Low' },
  { value: 'medium', label: 'Medium' },
  { value: 'high', label: 'High' },
]

export default function Example() {
  const [value, setValue] = useState<string[]>([])
  return (
    <Stack style={{ maxWidth: 320 }}>
      <Field label="Priority" required errorText={value.length ? undefined : 'Choose a priority'}>
        <Select items={priorities} value={value} onValueChange={(d) => setValue(d.value)} />
      </Field>
    </Stack>
  )
}

Props

Prop	Type	Default	Description
`items`*	`SelectItem[]`	-	The options.
`placeholder`	`string`	`Select...`	Shown when nothing is selected. Default: "Select...".
`size`	`"sm" \| "md" \| "lg"`	`md`	sm 34px, md 40px, lg 44px. Default: md.
`aria-label`	`string`	-	Accessible name when there is no Field label.
`defaultValue`	`string[]`	-	The initial default value of the select when rendered. Use when you don't need to control the value of the select.
`value`	`string[]`	-	The controlled keys of the selected items
`name`	`string`	-	The `name` attribute of the underlying select.
`disabled`	`boolean`	-	Whether the select is disabled
`invalid`	`boolean`	-	Whether the select is invalid
`onValueChange`	`((details: ValueChangeDetails<SelectItem>) => void)`	-	The callback fired when the selected item changes.
`multiple`	`boolean`	-	Whether to allow multiple selection

The remaining props of Ark UI’s Select.Root are accepted too.

Items

Field	Type	Description
`value`	`string`	The value stored in `value` and submitted with a form.
`label`	`string`	The text shown.
`disabled`	`boolean`	The option cannot be chosen.
`leading`	`ReactNode`	Shown before the label in the list, e.g. an icon or avatar.

Accessibility and usage

Inside a Field, the Field label names the trigger. Outside one, pass aria-label.
Define items outside the component or with useMemo, so the option list is not rebuilt on every render.
A hidden native <select> is rendered, so name submits the value with a form.
For a long list that needs searching, use Combobox.