Skip to main content
Kaleidoscope

Select

HW

Allow one or more options to be selected from a menu of options.

Single Select

A standard Select menu. Useful for allowing selection from a list without occupying too much space.

Editable example
() => {
  const [value, setValue] = React.useState("");

  return (
    <Select
      placeholder="Select an option"
      label="Example select"
      value={value}
      onChange={setValue}
    >
      <SelectOption value="option1">Option 1</SelectOption>
      <SelectOption value="option2">Option 2</SelectOption>
      <SelectOption value="option3">Option 3</SelectOption>
    </Select>
  );
}

Best practices

  1. Use with three or more options. For fewer options, or when the options have very short labels, consider using a .
  2. For long lists, it's better to use the Combobox because it can be searched/filtered.
  3. For menus that are triggered by a button and options that perform an action, use an .

Sizes

Like with all controls, match the sizing of the Select with other controls surrounding it. Smaller sizes are used for more densely packed interfaces, while larger sizes are good for less populated forms.

Editable example
() => {
  const [xSmall, setXSmall] = React.useState("");
  const [small, setSmall] = React.useState("");
  const [medium, setMedium] = React.useState("");
  const [large, setLarge] = React.useState("");

  const options = ["Option 1", "Option 2", "Option 3", "Option 4"];

  return (
    <>
      <Select label="Extra Small" placeholder="Select an option" value={xSmall} onChange={setXSmall} size="xs">
        {options.map((option) => (
          <SelectOption key={option} value={option}>{option}</SelectOption>
        ))}
      </Select>
      <Select label="Small" placeholder="Select an option" value={small} onChange={setSmall} size="s">
        {options.map((option) => (
          <SelectOption key={option} value={option}>{option}</SelectOption>
        ))}
      </Select>
      <Select label="Medium" placeholder="Select an option" value={medium} onChange={setMedium} size="m">
        {options.map((option) => (
          <SelectOption key={option} value={option}>{option}</SelectOption>
        ))}
      </Select>
      <Select label="Large" placeholder="Select an option" value={large} onChange={setLarge} size="l">
        {options.map((option) => (
          <SelectOption key={option} value={option}>{option}</SelectOption>
        ))}
      </Select>
    </>
  );
}

Multi select

Simply use the multiselect prop and provide an array as a value to handle multiple selection.

Editable example
() => {
  const [selected, setSelected] = React.useState([]);

  return (
    <Select
      multiselect
      label="Select a cephalopod"
      placeholder="Select one or more options"
      value={selected}
      onChange={setSelected}
    >
      <SelectOption value="octopus">Octopus</SelectOption>
      <SelectOption value="cuttlefish">Cuttlefish</SelectOption>
      <SelectOption value="squid">Squid</SelectOption>
      <SelectOption value="nautilus">Nautilus</SelectOption>
    </Select>
  );
}

Theme

Set the visual theme for the select. The theme prop is optional — when not provided, the select will inherit the theme from its parent context.

Editable example
() => {
  const [selected, setSelected] = React.useState("");

  return (
    <Card theme={CardTheme.Dark}>
      <div className="space-inset-m">
        <Select
          label="Select a cephalopod"
          placeholder="Select one or more options"
          value={selected}
          onChange={setSelected}
          theme="dark"
        >
          <SelectOption value="octopus">Octopus</SelectOption>
          <SelectOption value="cuttlefish">Cuttlefish</SelectOption>
          <SelectOption value="squid">Squid</SelectOption>
          <SelectOption value="nautilus">Nautilus</SelectOption>
        </Select>
      </div>
    </Card>
  );
}

Icon

An icon can be shown inside the select input with the icon prop.

Editable example
() => {
  const [value, setValue] = React.useState("");

  return (
    <Select
      placeholder="Select a page"
      label="Page"
      value={value}
      onChange={setValue}
      icon={<Library />}
    >
      <SelectOption value="home">Home</SelectOption>
      <SelectOption value="about">About</SelectOption>
      <SelectOption value="contact">Contact</SelectOption>
    </Select>
  );
}

End element

Additional content can be placed at the end of the select input with endElement.

Editable example
() => {
  const [value, setValue] = React.useState("");

  return (
    <Select
      placeholder="Select an option"
      label="Example"
      value={value}
      onChange={setValue}
      endElement={<Text size="xs">Required</Text>}
    >
      <SelectOption value="option1">Option 1</SelectOption>
      <SelectOption value="option2">Option 2</SelectOption>
    </Select>
  );
}

Disabled

Disable the select to prevent interaction.

Editable example
<Select
  placeholder="Select an option"
  label="Disabled select"
  value=""
  onChange={() => {}}
  disabled
>
  <SelectOption value="option1">Option 1</SelectOption>
  <SelectOption value="option2">Option 2</SelectOption>
</Select>

Panel width and alignment

By default the menu panel matches the width of the select input and aligns to the start. Set a custom panelWidth in pixels or change panelAlignment to "center" if you need different positioning.

Editable example
() => {
  const [value, setValue] = React.useState("");

  return (
    <Select
      placeholder="Select an option"
      label="Wide panel"
      value={value}
      onChange={setValue}
      panelWidth={400}
      panelAlignment="center"
    >
      <SelectOption value="option1">Option 1</SelectOption>
      <SelectOption value="option2">Option 2</SelectOption>
      <SelectOption value="option3">Option 3</SelectOption>
    </Select>
  );
}

On close

The onClose callback fires when the menu is closed.

Errors

Use the error prop to display validation error messages.

Editable example
() => {
  const [value, setValue] = React.useState("");

  return (
    <Select
      placeholder="Select an option"
      label="Example select"
      value={value}
      onChange={setValue}
      error="Please select an option"
    >
      <SelectOption value="option1">Option 1</SelectOption>
      <SelectOption value="option2">Option 2</SelectOption>
      <SelectOption value="option3">Option 3</SelectOption>
    </Select>
  );
}

SelectOption

SelectOption accepts a few props to customise each item in the menu.

Icons and elements

Add an icon or endElement to individual options.

Editable example
() => {
  const [value, setValue] = React.useState("");

  return (
    <Select placeholder="Select an option" label="Options with icons" value={value} onChange={setValue}>
      <SelectOption value="edit" icon={<Edit />}>Edit</SelectOption>
      <SelectOption value="archive" icon={<Archive />}>Archive</SelectOption>
      <SelectOption value="export" icon={<Popout />} endElement={<ArrowRight />}>Export</SelectOption>
    </Select>
  );
}

Disabled options

Individual options can be disabled.

Editable example
() => {
  const [value, setValue] = React.useState("");

  return (
    <Select placeholder="Select an option" label="Some disabled" value={value} onChange={setValue}>
      <SelectOption value="option1">Option 1</SelectOption>
      <SelectOption value="option2" disabled>Option 2 (disabled)</SelectOption>
      <SelectOption value="option3">Option 3</SelectOption>
    </Select>
  );
}

Keep open on select

By default the menu closes after selecting an option. Set keepOpenOnSelect on individual options to override this.

Custom display name

By default the selected option shows its children text in the input. Use the name prop to show a different value when selected.

Accessibility

Always provide a meaningful label even when using the labelHidden prop — it will only visually hide the label but still be read by a screen reader.