Combobox

Combobox is for picking from a long list: countries, owners, contacts. Typing filters the options by label. For a short list, use Select.

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

Source · Figma

Examples

Basic

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

// Keep the array outside the component (or in useMemo) so its identity is stable.
const countries = ['Bhutan', 'Canada', 'India', 'Nepal', 'Thailand', 'United States'].map(
  (name) => ({ value: name.toLowerCase(), label: name }),
)

export default function Example() {
  return (
    <div style={{ maxWidth: 320 }}>
      <Combobox aria-label="Country" items={countries} placeholder="Search country..." />
    </div>
  )
}

Inside a Field, controlled

value is an array of option values, as in Select. Inside a Field the visible label names the input, so aria-label is not needed.

Country

Selected value: bhutan

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

const countries = ['Bhutan', 'Canada', 'India', 'Nepal', 'Thailand', 'United States'].map(
  (name) => ({ value: name.toLowerCase(), label: name }),
)

export default function Example() {
  const [value, setValue] = useState<string[]>(['bhutan'])
  return (
    <div style={{ maxWidth: 320 }}>
      <Field label="Country" helperText={`Selected value: ${value[0] ?? 'none'}`}>
        <Combobox
          items={countries}
          value={value}
          defaultInputValue="Bhutan"
          onValueChange={(d) => setValue(d.value)}
        />
      </Field>
    </div>
  )
}

Props

Prop	Type	Default	Description
items*	SelectItem[]	-	The options. Typing filters them by label.
placeholder	string	Search...	The placeholder text of the combobox's input
size	"sm" | "md" | "lg"	md	sm 34px, md 40px, lg 44px. Default: md.
emptyText	string	No results	Shown when nothing matches. Default: "No results".
aria-label	string	-	Defines a string value that labels the current element.
defaultValue	string[]	-	The initial value of the combobox's selected items when rendered. Use when you don't need to control the value of the combobox's selected items.
value	string[]	-	The controlled value of the combobox's selected items
name	string	-	The name attribute of the combobox's input. Useful for form submission
disabled	boolean	-	Whether the combobox is disabled
invalid	boolean	-	Whether the combobox is invalid
inputValue	string	-	The controlled value of the combobox's input
defaultInputValue	string	-	The initial value of the combobox's input when rendered. Use when you don't need to control the value of the combobox's input.
onValueChange	((details: ValueChangeDetails<SelectItem>) => void)	-	Function called when a new item is selected
multiple	boolean	-	Whether to allow multiple selection. **Good to know:** When multiple is true, the selectionBehavior is automatically set to clear. It is recommended to render the selected items in a separate container.

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

Items

Items have the same shape as Select items.

Field	Type	Description
value	string	The value stored in value and submitted with a form.
label	string	The text shown, and the text the filter matches.
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

• Keep items stable: define the array outside the component or wrap it in useMemo. The list is reset whenever the array identity changes.
• The filter matches any part of the label and ignores case and accents.
• The list opens on click as well as on typing. emptyText is shown when nothing matches.
• Give it an aria-label when it is not inside a Field.