Select

When to useLink to "When to use"

• Five or more options, or a list that would take too much room as radios.
• A value that is submitted with a form (a country, a language, a database).
• Options that benefit from a description or an icon.

Use something else when:

• there are only a few options: RadioGroup or SegmentedControl
• the user types free text: TextField

UsageLink to "Usage"

import { Select } from "@arshad-shah/cynosure";

<Select
  label="Fruit"
  name="fruit"
  placeholder="Choose a fruit"
  options={[
    { value: "apple", label: "Apple" },
    { value: "pear", label: "Pear", description: "Seasonal" },
    { value: "plum", label: "Plum", disabled: true },
  ]}
  onChange={setFruit}
/>

Controlled useLink to "Controlled use"

Pass value and onChange(value) to own the state, or defaultValue to start with a selection.

Long lists and labelsLink to "Long lists and labels"

The list has a maximum height and scrolls. Long labels truncate with an ellipsis in the trigger and the list. The list opens above the trigger when there is no room below.

Options and statesLink to "Options and states"

• variant: outline (default) or soft.
• size: xs, sm, md or lg. xs is a 20px trigger with smaller text and chevron for dense desktop chrome; it is still 24px to press (44px on coarse pointers) and its label is set as for sm.
• error and description: shown under the field and linked to the trigger.
• labels: override placeholder, empty (no options) and required (validation message).
• labelHidden: hides the label visually while it still names the trigger. Prefer a visible label.

Trailing text, dimmed options and a footer actionLink to "Trailing text, dimmed options and a footer action"

An option's trailing is drawn at the end of its row in the list, smaller and muted (a shortcut, a count); the trigger shows the label only. dimmed draws an option muted while it stays choosable. footer pins an action under the options, { label, icon?, onSelect }: it is the last option the arrow keys reach (End and PageDown too), and Enter, Space or a press closes the list and runs it. The value does not change, and Tab passes over it.

Coloured iconsLink to "Coloured icons"

iconTone and iconColor colour an option's icon and mean what Icon's tone and color mean: iconTone is a semantic colour (accent, neutral, danger, success, warning, info, muted), iconColor is any CSS colour and overrides it (brand draws a brand mark in its owner's colour). The colour shows in the list, on the highlighted and the selected option, and in the trigger once the option is chosen. Without the two fields an icon takes the text colour.

A disabled option shows its icon without the colour, muted with the rest of the row, and so does the trigger of a disabled Select. Tone colours keep a contrast of 3:1 against the highlight. With your own colour, check it in light and dark. The label must make sense without the colour.

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Pattern: a select-only combobox following the WAI-ARIA authoring practices, with a listbox of options.
• Forms: a hidden input carries name and the value, so FormData, reset and required validation work.
• Outside click: closes the list.

TouchLink to "Touch"

On coarse pointers (phones and tablets) option rows grow to 44px.

ThemingLink to "Theming"

Tokens: --cy-select-{radius,bg,border,list-bg,list-shadow,list-max-height,option-active-bg}; an xs trigger is --cy-control-height-xs tall. The list is an OptionList: the list-* and option-* tokens set its --cy-option-list-* tokens.

createTheme({ components: { select: { radius: "10px", listMaxHeight: "240px" } } });

RelatedLink to "Related"

RadioGroup · SegmentedControl · TextField