Select (Alpha) | Coinbase Design System

Select (Alpha)

@coinbase/cds-web@9.28.0

A flexible select component for both single and multi-selection, built for web applications with comprehensive accessibility support.

import { Select } from '@coinbase/cds-web/alpha/select'

Source

Storybook

View as Markdown

Peer dependencies

framer-motion: ^10.18.0,
react-dom: ^18.0.0 || ~19.1.2

Single Select

Basic single selection with predefined options.

Multi-Select

Multi-selection mode allows users to select multiple options from the list.

Single Select with Groups

Organize options into logical groups for better organization.

Multi-Select with Groups

Use groups in multi-select mode to organize selections.

Alignment

The Select component supports aligning the selected value(s) using the align prop.

Accessibility Props

The Select component supports comprehensive accessibility features including custom labels and roles.

Variant Props

The Select component supports different visual variants for various states and contexts.

With Disabled Option Group

Disable entire groups to prevent selection of those options.

Sizes

size accepts s, m, and l. Defaults to l.

Multi-selection mode works at every size. When size="s", the dropdown uses compact row density to match the smaller control.

Disabled States

Components can be disabled entirely or have individual options disabled.

Options with Descriptions

Options can include descriptions for additional context.

Start Node

Add an icon or element at the start of the select control.

End Node

Add an icon or element at the end of the select control.

Custom Icons

Add custom icons as accessories or media to options.

Empty State

Handle empty option lists with custom messages or components.

Controlled Open State

Control the open/closed state of the dropdown programmatically.

Multi-Select with Max Display

Limit the number of selected items shown when using multi-select.

Custom Select All labels

Customize the select all functionality in multi-select mode.

Label Variants

Different label positioning options for the Select component.

Very Long Labels

Handle extremely long option labels that may need special treatment.

Custom Long Placeholder

Use extended placeholder text for more descriptive empty states.

Mixed Options

Options with and without descriptions in the same select.

Options with Only Accessory

Add accessories without media for cleaner layouts.

Options with Only Media

Add media icons without accessories for visual identification.

Variants with Additional Props

Combine variants with other properties for complex states.

Long Helper Text

Extended helper text for detailed instructions.

No Label

Select without a visible label (accessibility label still required).

Complex Nested Options

Options with special characters, emojis, and complex content.

Stress Test

Many options with various configurations for performance testing.

Value Display

Show the selected value in another component.

Options with Only Description

Options that only have descriptions without labels.

Custom styles

You can use custom styles on the various subcomponents in Select.

Custom class names

You can use custom class names on the various subcomponents in Select.

function CustomClassNamesExamples() {
  const exampleOptions = [
    { value: null, label: 'Remove selection' },
    { value: '1', label: 'Option 1' },
    { value: '2', label: 'Option 2' },
    { value: '3', label: 'Option 3' },
    { value: '4', label: 'Option 4' },
  ];
  const [value, setValue] = useState('1');

  return (
    <Select
      classNames={{
        control: customControlStyles,
        option: customOptionStyles,
      }}
      label="Single select - class names"
      onChange={setValue}
      options={exampleOptions}
      placeholder="Empty value"
      value={value}
    />
  );
}

Custom Label

You can pass a ReactNode to label to render a custom label. If you want to include a tooltip, ensure the touch target is at least 24x24 for accessibility compliance.

Borderless

You can remove the border from the select control by setting bordered to false. Now Select will only show a border when focused.

Custom components

Select is highly customizable. Use the Component props to customize the various subcomponents in Select.

Customizable subcomponents

SelectControlComponent: Trigger component used to open and close the Select.
SelectDropdownComponent: Component which renders the dropdown menu and SelectOptionComponents.
SelectOptionComponent: Component which renders the content of an option in the select.
SelectAllOptionComponent: Component which renders the Select All option in a multi-select select menu.
SelectEmptyDropdownContentsComponent: Component which renders as the select menu's content when no options are passed in.

Below is a diagram to help visualize the Select anatomy.

Select
├── SelectControlComponent (trigger to open/close)
└── SelectDropdownComponent (dropdown menu)
    ├── SelectAllOptionComponent
    ├── SelectOptionComponent (option 1)
    ├── SelectOptionComponent (option 2)
    ├── SelectOptionComponent (option 3)
    └── SelectOptionComponent (option N...)

Example

function CustomComponentExamples() {
  const exampleOptions = [
    { value: null, label: 'Remove selection' },
    { value: '1', label: 'Option 1' },
    { value: '2', label: 'Option 2' },
    { value: '3', label: 'Option 3' },
    { value: '4', label: 'Option 4' },
  ];
  const [value, setValue] = useState('1');

  const CustomControlComponent = ({ value, setOpen }) => {
    return <Button onClick={() => setOpen(true)}>{value ?? 'Empty value'}</Button>;
  };

  const CustomOptionComponent = ({ value, onClick }) => {
    return (
      <HStack justifyContent="center">
        <Spinner size={4} />
        <Button transparent onClick={() => onClick?.(value)} width="80%">
          {value ?? 'Empty value'}
        </Button>
        <Spinner size={4} />
      </HStack>
    );
  };

  return (
    <Select
      SelectControlComponent={CustomControlComponent}
      SelectOptionComponent={CustomOptionComponent}
      label="Single select - custom components"
      onChange={setValue}
      options={exampleOptions}
      placeholder="Empty value"
      value={value}
    />
  );
}

Single Select​

Multi-Select​

Single Select with Groups​

Multi-Select with Groups​

Alignment​

Accessibility Props​

Variant Props​

With Disabled Option Group​

Sizes​

Disabled States​

Options with Descriptions​

Start Node​

End Node​

Custom Icons​

Empty State​

Controlled Open State​

Multi-Select with Max Display​

Custom Select All labels​

Label Variants​

Very Long Labels​

Custom Long Placeholder​

Mixed Options​

Options with Only Accessory​

Options with Only Media​

Variants with Additional Props​

Long Helper Text​

No Label​

Complex Nested Options​

Stress Test​

Value Display​

Options with Only Description​

Custom styles​

Custom class names​

Custom Label​

Borderless​

Custom components​

Customizable subcomponents​

Example​

Is this page useful?