# SelectAlpha

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

## Import

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

## Examples

:::note Duplicate Values
Avoid using options with duplicate values. Each option's `value` should be unique within the options array to ensure proper selection behavior.
:::

### Single Select

Basic single selection with predefined options.

```jsx live
function SingleSelectExample() {
  const [value, setValue] = useState('1');

  const options = [
    { value: '1', label: 'Option 1' },
    { value: '2', label: 'Option 2' },
    { value: '3', label: 'Option 3' },
    { value: '4', label: 'Option 4' },
  ];

  return (
    <Select
      label="Choose an option"
      value={value}
      onChange={setValue}
      options={options}
      placeholder="Select an option"
    />
  );
}
```

### Multi-Select

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

:::note Disabled Options and Select All
Disabled options and options inside disabled groups will be skipped when "Select all" is pressed. Only enabled options will be selected.
:::

```jsx live
function MultiSelectExample() {
  const { value, onChange } = useMultiSelect({
    initialValue: ['1', '3', '7', '8', '9', '10'],
  });

  const options = [
    { value: '1', label: 'Option 1' },
    { value: '2', label: 'Option 2' },
    { value: '3', label: 'Option 3' },
    { value: '4', label: 'Option 4' },
    { value: '5', label: 'Option 5' },
    { value: '6', label: 'Option 6' },
    { value: '7', label: 'Option 7' },
    { value: '8', label: 'Option 8' },
    { value: '9', label: 'Option 9' },
    { value: '10', label: 'Option 10' },
  ];

  return (
    <Select
      type="multi"
      label="Choose multiple options"
      value={value}
      onChange={onChange}
      options={options}
      placeholder="Select options"
      selectAllLabel="Select all options"
      clearAllLabel="Clear all selections"
      maxSelectedOptionsToShow={4}
    />
  );
}
```

### Single Select with Groups

Organize options into logical groups for better organization.

```jsx live
function SingleSelectWithGroupsExample() {
  const [value, setValue] = useState(null);

  const groupedOptions = [
    {
      label: 'Group A',
      options: [
        { value: '1', label: 'Option 1' },
        { value: '2', label: 'Option 2' },
        { value: '3', label: 'Option 3' },
      ],
    },
    {
      label: 'Group B',
      options: [
        { value: '4', label: 'Option 4' },
        { value: '5', label: 'Option 5' },
      ],
    },
    {
      label: 'Group C',
      options: [{ value: '6', label: 'Option 6' }],
    },
  ];

  return (
    <Select
      label="Choose an option"
      value={value}
      onChange={setValue}
      options={groupedOptions}
      placeholder="Select an option"
    />
  );
}
```

### Multi-Select with Groups

Use groups in multi-select mode to organize selections.

```jsx live
function MultiSelectWithGroupsExample() {
  const { value, onChange } = useMultiSelect({
    initialValue: [],
  });

  const groupedOptions = [
    {
      label: 'Group A',
      options: [
        { value: '1', label: 'Option 1' },
        { value: '2', label: 'Option 2' },
        { value: '3', label: 'Option 3' },
      ],
    },
    {
      label: 'Group B',
      options: [
        { value: '4', label: 'Option 4' },
        { value: '5', label: 'Option 5' },
      ],
    },
    {
      label: 'Group C',
      options: [{ value: '6', label: 'Option 6' }],
    },
  ];

  return (
    <Select
      type="multi"
      label="Choose multiple options"
      value={value}
      onChange={onChange}
      options={groupedOptions}
      placeholder="Select options"
      selectAllLabel="Select all options"
      clearAllLabel="Clear all selections"
    />
  );
}
```

### Accessibility Props

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

```jsx live
function AccessibilityExample() {
  const [value, setValue] = useState('2');

  const options = [
    { value: '1', label: 'High Priority' },
    { value: '2', label: 'Medium Priority' },
    { value: '3', label: 'Low Priority' },
  ];

  return (
    <Select
      label="Task Priority"
      value={value}
      onChange={setValue}
      options={options}
      accessibilityLabel="Task priority level options"
      controlAccessibilityLabel="Select task priority level"
      accessibilityRoles={{
        dropdown: 'listbox',
        option: 'option',
      }}
      placeholder="Choose priority level"
      helperText="Select the appropriate priority for this task"
    />
  );
}
```

### Variant Props

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

```jsx live
function VariantExample() {
  const [positiveValue, setPositiveValue] = useState('success');
  const [negativeValue, setNegativeValue] = useState('');

  const positiveOptions = [
    { value: 'success', label: 'Success' },
    { value: 'completed', label: 'Completed' },
    { value: 'approved', label: 'Approved' },
  ];

  const negativeOptions = [
    { value: 'error', label: 'Error' },
    { value: 'failed', label: 'Failed' },
    { value: 'rejected', label: 'Rejected' },
  ];

  return (
    <VStack gap={4}>
      <Select
        label="Positive Status"
        value={positiveValue}
        onChange={setPositiveValue}
        options={positiveOptions}
        variant="positive"
        helperText="This shows a positive state"
        placeholder="Select positive status"
      />

      <Select
        label="Negative Status"
        value={negativeValue}
        onChange={setNegativeValue}
        options={negativeOptions}
        variant="negative"
        helperText="This shows an error state"
        placeholder="Select negative status"
      />
    </VStack>
  );
}
```

### With Disabled Option Group

Disable entire groups to prevent selection of those options.

```jsx live
function DisabledGroupExample() {
  const [value, setValue] = useState(null);

  const groupedOptions = [
    {
      label: 'Available Options',
      options: [
        { value: '1', label: 'Option 1' },
        { value: '2', label: 'Option 2' },
        { value: '3', label: 'Option 3' },
      ],
    },
    {
      label: 'Unavailable Options (Group Disabled)',
      disabled: true,
      options: [
        { value: '4', label: 'Option 4' },
        { value: '5', label: 'Option 5' },
        { value: '6', label: 'Option 6' },
      ],
    },
    {
      label: 'More Available Options',
      options: [
        { value: '7', label: 'Option 7' },
        { value: '8', label: 'Option 8' },
      ],
    },
  ];

  return (
    <Select
      label="Choose an option"
      value={value}
      onChange={setValue}
      options={groupedOptions}
      placeholder="Select an option"
    />
  );
}
```

### Compact Mode

The Select component can be rendered in a compact size for denser UIs.

```jsx live
function CompactExample() {
  const [value, setValue] = useState('1');

  const options = [
    { value: '1', label: 'Small Option 1' },
    { value: '2', label: 'Small Option 2' },
    { value: '3', label: 'Small Option 3' },
  ];

  return (
    <Select
      compact
      label="Compact Select"
      value={value}
      onChange={setValue}
      options={options}
      placeholder="Select an option"
      helperText="This is a compact select component"
    />
  );
}
```

You can also use multi-selection mode while in a compact size.

```jsx live
function CompactMultiSelectExample() {
  const { value, onChange } = useMultiSelect({
    initialValue: ['1', '3', '7', '8', '9', '10'],
  });

  const options = [
    { value: '1', label: 'Option 1' },
    { value: '2', label: 'Option 2' },
    { value: '3', label: 'Option 3' },
    { value: '4', label: 'Option 4' },
    { value: '5', label: 'Option 5' },
    { value: '6', label: 'Option 6' },
    { value: '7', label: 'Option 7' },
    { value: '8', label: 'Option 8' },
    { value: '9', label: 'Option 9' },
    { value: '10', label: 'Option 10' },
  ];

  return (
    <Select
      compact
      type="multi"
      label="Choose multiple options"
      value={value}
      onChange={onChange}
      options={options}
      placeholder="Select options"
      selectAllLabel="Select all options"
      clearAllLabel="Clear all selections"
      maxSelectedOptionsToShow={2}
    />
  );
}
```

### Disabled States

Components can be disabled entirely or have individual options disabled.

```jsx live
function DisabledExample() {
  const [value1, setValue1] = useState('2');
  const [value2, setValue2] = useState('2');

  const optionsWithDisabled = [
    { value: '1', label: 'Option 1', disabled: true },
    { value: '2', label: 'Option 2' },
    { value: '3', label: 'Option 3' },
    { value: '4', label: 'Option 4', disabled: true },
  ];

  return (
    <VStack gap={4}>
      <Select
        label="Disabled Select"
        value={value1}
        onChange={setValue1}
        options={optionsWithDisabled}
        disabled
        placeholder="This select is disabled"
      />

      <Select
        label="Select with Disabled Options"
        value={value2}
        onChange={setValue2}
        options={optionsWithDisabled}
        placeholder="Some options are disabled"
      />
    </VStack>
  );
}
```

### Options with Descriptions

Options can include descriptions for additional context.

```jsx live
function DescriptionExample() {
  const [value, setValue] = useState('1');

  const optionsWithDescriptions = [
    { value: '1', label: 'Bitcoin', description: 'The first cryptocurrency' },
    { value: '2', label: 'Ethereum', description: 'Smart contract platform' },
    { value: '3', label: 'USDC', description: 'USD-backed stablecoin' },
    { value: '4', label: 'Solana', description: 'High-performance blockchain' },
  ];

  return (
    <Select
      label="Select Cryptocurrency"
      value={value}
      onChange={setValue}
      options={optionsWithDescriptions}
      placeholder="Choose a cryptocurrency"
    />
  );
}
```

### Start Node

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

```jsx live
function StartNodeExample() {
  const [value, setValue] = useState('1');

  const options = [
    { value: '1', label: 'Search Result 1' },
    { value: '2', label: 'Search Result 2' },
    { value: '3', label: 'Search Result 3' },
  ];

  return (
    <Select
      label="Search"
      value={value}
      onChange={setValue}
      options={options}
      startNode={<Icon color="fg" name="search" />}
      placeholder="Search for options"
    />
  );
}
```

### End Node

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

```jsx live
function EndNodeExample() {
  const [value, setValue] = useState('1');

  const options = [
    { value: '1', label: 'Search Result 1' },
    { value: '2', label: 'Search Result 2' },
    { value: '3', label: 'Search Result 3' },
  ];

  return (
    <Select
      endNode={<Icon alignItems="center" color="fg" name="search" />}
      label="Single select - end node"
      onChange={setValue}
      options={options}
      placeholder="Empty value"
      value={value}
    />
  );
}
```

### Custom Icons

Add custom icons as accessories or media to options.

```jsx live
function CustomIconsExample() {
  const [value, setValue] = useState('1');

  const optionsWithIcons = [
    {
      value: '1',
      label: 'Favorites',
      accessory: <Icon color="fg" name="star" />,
      media: <Icon color="fg" name="heart" />,
    },
    {
      value: '2',
      label: 'Verified',
      accessory: <Icon color="fg" name="checkmark" />,
      media: <Icon color="fg" name="shield" />,
    },
    {
      value: '3',
      label: 'Settings',
      accessory: <Icon color="fg" name="caretRight" />,
      media: <Icon color="fg" name="gear" />,
    },
  ];

  return (
    <Select
      label="Choose Action"
      value={value}
      onChange={setValue}
      options={optionsWithIcons}
      placeholder="Select an action"
    />
  );
}
```

### Empty State

Handle empty option lists with custom messages or components.

```jsx live
function EmptyStateExample() {
  const [searchTerm, setSearchTerm] = useState('');
  const [value, setValue] = useState(null);

  const allOptions = [];

  const filteredOptions = searchTerm
    ? allOptions.filter((opt) => opt.label.toLowerCase().includes(searchTerm.toLowerCase()))
    : allOptions;

  return (
    <Select
      label="Filtered Select"
      value={value}
      onChange={setValue}
      options={filteredOptions}
      emptyOptionsLabel="No matching options found"
      placeholder="Select an option"
    />
  );
}
```

### Controlled Open State

Control the open/closed state of the dropdown programmatically.

```jsx live
function ControlledOpenExample() {
  const [value, setValue] = useState('1');
  const [open, setOpen] = useState(false);

  const options = [
    { value: '1', label: 'Option 1' },
    { value: '2', label: 'Option 2' },
    { value: '3', label: 'Option 3' },
  ];

  return (
    <VStack gap={4}>
      <Button onClick={() => setOpen(!open)}>{open ? 'Close Dropdown' : 'Open Dropdown'}</Button>

      <Select
        label="Controlled Select"
        value={value}
        onChange={setValue}
        options={options}
        open={open}
        setOpen={setOpen}
        placeholder="Select an option"
        disableClickOutsideClose
      />
    </VStack>
  );
}
```

### Multi-Select with Max Display

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

```jsx live
function MaxDisplayExample() {
  const { value, onChange } = useMultiSelect({
    initialValue: ['1', '2', '3', '4', '5'],
  });

  const options = Array.from({ length: 20 }, (_, i) => ({
    value: (i + 1).toString(),
    label: `Option ${i + 1}`,
  }));

  return (
    <Select
      type="multi"
      label="Select Multiple Items"
      value={value}
      onChange={onChange}
      options={options}
      maxSelectedOptionsToShow={3}
      placeholder="Select options"
      helperText="Only showing first 3 selected items"
    />
  );
}
```

### Custom Select All labels

Customize the select all functionality in multi-select mode.

```jsx live
function CustomSelectAllExample() {
  const { value, onChange } = useMultiSelect({
    initialValue: ['1'],
  });

  const options = [
    { value: '1', label: 'Monday' },
    { value: '2', label: 'Tuesday' },
    { value: '3', label: 'Wednesday' },
    { value: '4', label: 'Thursday' },
    { value: '5', label: 'Friday' },
    { value: '6', label: 'Saturday' },
    { value: '7', label: 'Sunday' },
  ];

  return (
    <Select
      type="multi"
      label="Select Days"
      value={value}
      onChange={onChange}
      options={options}
      selectAllLabel="Select all days of the week"
      clearAllLabel="Clear all days"
      placeholder="Choose days"
    />
  );
}
```

### Label Variants

Different label positioning options for the Select component.

```jsx live
function LabelVariantExample() {
  const [value1, setValue1] = useState('');
  const [value2, setValue2] = useState('');

  const options = [
    { value: '1', label: 'Option 1' },
    { value: '2', label: 'Option 2' },
    { value: '3', label: 'Option 3' },
  ];

  return (
    <VStack gap={4}>
      <Select
        label="Default Label Position"
        value={value1}
        onChange={setValue1}
        options={options}
        placeholder="Select an option"
      />

      <Select
        label="Inside Label"
        labelVariant="inside"
        value={value2}
        onChange={setValue2}
        options={options}
        placeholder="Select an option"
      />
    </VStack>
  );
}
```

### Very Long Labels

Handle extremely long option labels that may need special treatment.

```jsx live
function VeryLongLabelsExample() {
  const [value, setValue] = useState('1');

  const longOptions = [
    {
      value: '1',
      label:
        'This is an extremely long option label that should test how the component handles very long text content that might overflow or wrap',
    },
    {
      value: '2',
      label:
        'Another super long option label with even more text to see how it wraps or truncates in the UI when space is limited',
    },
    {
      value: '3',
      label: 'Short',
    },
    {
      value: '4',
      label: 'A moderately long label that is somewhere between short and extremely long',
    },
  ];

  return (
    <Select
      label="Options with Very Long Labels"
      value={value}
      onChange={setValue}
      options={longOptions}
      placeholder="Select an option"
    />
  );
}
```

### Custom Long Placeholder

Use extended placeholder text for more descriptive empty states.

```jsx live
function LongPlaceholderExample() {
  const [value, setValue] = useState(null);

  const options = [
    { value: '1', label: 'Option 1' },
    { value: '2', label: 'Option 2' },
    { value: '3', label: 'Option 3' },
  ];

  return (
    <Select
      label="Select with Long Placeholder"
      value={value}
      onChange={setValue}
      options={options}
      placeholder="This is a very long placeholder text that provides detailed instructions about what the user should select"
    />
  );
}
```

### Mixed Options

Options with and without descriptions in the same select.

```jsx live
function MixedOptionsExample() {
  const [value, setValue] = useState('1');

  const mixedOptions = [
    { value: '1', label: 'Bitcoin', description: 'The original cryptocurrency' },
    { value: '2', label: 'Ethereum' },
    { value: '3', label: 'USDC', description: 'USD-backed stablecoin' },
    { value: '4', label: 'Solana' },
    { value: '5', label: 'Polygon', description: 'Layer 2 scaling solution' },
  ];

  return (
    <Select
      label="Mixed Option Types"
      value={value}
      onChange={setValue}
      options={mixedOptions}
      placeholder="Choose an asset"
    />
  );
}
```

### Options with Only Accessory

Add accessories without media for cleaner layouts.

```jsx live
function OnlyAccessoryExample() {
  const [value, setValue] = useState('1');

  const optionsWithAccessory = [
    {
      value: '1',
      label: 'Favorites',
      accessory: <Icon color="fg" name="star" />,
    },
    {
      value: '2',
      label: 'Verified',
      accessory: <Icon color="fg" name="checkmark" />,
    },
    {
      value: '3',
      label: 'Premium',
      accessory: <Icon color="fg" name="search" />,
    },
  ];

  return (
    <Select
      label="Options with Accessories Only"
      value={value}
      onChange={setValue}
      options={optionsWithAccessory}
      placeholder="Select an option"
    />
  );
}
```

### Options with Only Media

Add media icons without accessories for visual identification.

```jsx live
function OnlyMediaExample() {
  const [value, setValue] = useState('1');

  const optionsWithMedia = [
    {
      value: '1',
      label: 'Home',
      media: <Icon color="fg" name="home" />,
    },
    {
      value: '2',
      label: 'Profile',
      media: <Icon color="fg" name="search" />,
    },
    {
      value: '3',
      label: 'Settings',
      media: <Icon color="fg" name="gear" />,
    },
  ];

  return (
    <Select
      label="Options with Media Only"
      value={value}
      onChange={setValue}
      options={optionsWithMedia}
      placeholder="Navigate to..."
    />
  );
}
```

### Variants with Additional Props

Combine variants with other properties for complex states.

```jsx live
function VariantCombinationsExample() {
  const [value1, setValue1] = useState('1');
  const [value2, setValue2] = useState('2');

  const options = [
    { value: '1', label: 'Option 1' },
    { value: '2', label: 'Option 2' },
    { value: '3', label: 'Option 3' },
  ];

  return (
    <VStack gap={4}>
      <Select
        compact
        variant="positive"
        startNode={<Icon color="fg" name="checkmark" />}
        label="Compact + Positive + Icon"
        value={value1}
        onChange={setValue1}
        options={options}
        helperText="Multiple props combined"
      />

      <Select
        disabled
        variant="negative"
        label="Disabled + Negative"
        value={value2}
        onChange={setValue2}
        options={options}
        helperText="Error state but disabled"
      />
    </VStack>
  );
}
```

### Long Helper Text

Extended helper text for detailed instructions.

```jsx live
function LongHelperTextExample() {
  const [value, setValue] = useState('1');

  const options = [
    { value: '1', label: 'Option 1' },
    { value: '2', label: 'Option 2' },
    { value: '3', label: 'Option 3' },
  ];

  return (
    <Select
      label="Select with Extended Helper"
      value={value}
      onChange={setValue}
      options={options}
      helperText="This is a very long helper text that provides extensive guidance about what the user should select. It might wrap to multiple lines depending on the container width and should remain readable."
      placeholder="Select an option"
    />
  );
}
```

### No Label

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

```jsx live
function NoLabelExample() {
  const [value, setValue] = useState('1');

  const options = [
    { value: '1', label: 'Option 1' },
    { value: '2', label: 'Option 2' },
    { value: '3', label: 'Option 3' },
  ];

  return (
    <Select
      accessibilityLabel="Hidden label select"
      value={value}
      onChange={setValue}
      options={options}
      placeholder="Select without visible label"
    />
  );
}
```

### Complex Nested Options

Options with special characters, emojis, and complex content.

```jsx live
function ComplexOptionsExample() {
  const [value, setValue] = useState('1');

  const complexOptions = [
    {
      value: '1',
      label: 'USD $100.00',
      description: 'United States Dollar',
      accessory: '🇺🇸',
    },
    {
      value: '2',
      label: 'EUR €85.50',
      description: 'Euro (€)',
      accessory: '🇪🇺',
    },
    {
      value: '3',
      label: 'GBP £73.25',
      description: 'British Pound Sterling',
      accessory: '🇬🇧',
    },
    {
      value: '4',
      label: 'JPY ¥11,050',
      description: '日本円 (Japanese Yen)',
      accessory: '🇯🇵',
    },
  ];

  return (
    <Select
      label="Currency Selection"
      value={value}
      onChange={setValue}
      options={complexOptions}
      placeholder="Choose currency"
    />
  );
}
```

### Stress Test

Many options with various configurations for performance testing.

```jsx live
function StressTestExample() {
  const [value, setValue] = useState('1');

  const stressOptions = Array.from({ length: 50 }, (_, i) => ({
    value: (i + 1).toString(),
    label: `Option ${i + 1}`,
    description: i % 3 === 0 ? `Description for option ${i + 1}` : undefined,
    disabled: i % 7 === 0,
    accessory: i % 5 === 0 ? <Icon color="fg" name="star" /> : undefined,
    media: i % 8 === 0 ? <Icon color="fg" name="heart" /> : undefined,
  }));

  return (
    <Select
      label="Stress Test - Many Options"
      value={value}
      onChange={setValue}
      options={stressOptions}
      placeholder="Choose from many options"
    />
  );
}
```

### Value Display

Show the selected value in another component.

```jsx live
function ValueDisplayExample() {
  const [value, setValue] = useState('btc');

  const cryptoOptions = [
    { value: 'btc', label: 'Bitcoin', description: 'BTC' },
    { value: 'eth', label: 'Ethereum', description: 'ETH' },
    { value: 'usdc', label: 'USD Coin', description: 'USDC' },
  ];

  const selectedOption = cryptoOptions.find((opt) => opt.value === value);

  return (
    <VStack gap={4}>
      <div
        style={{
          padding: '16px',
          borderRadius: '8px',
          backgroundColor: '#f0f0f0',
        }}
      >
        <Text font="headline">Selected Asset:</Text>
        <Text font="title2">{selectedOption?.label || 'None'}</Text>
        <Text font="body" color="fgSecondary">
          {selectedOption?.description || 'No selection'}
        </Text>
      </div>

      <Select
        label="Choose Cryptocurrency"
        value={value}
        onChange={setValue}
        options={cryptoOptions}
        placeholder="Select an asset"
      />
    </VStack>
  );
}
```

### Options with Only Description

Options that only have descriptions without labels.

```jsx live
function OnlyDescriptionExample() {
  const [value, setValue] = useState('1');

  const descriptionOnlyOptions = [
    { value: '1', description: 'First description without a label' },
    { value: '2', description: 'Second description only' },
    { value: '3', description: 'Third item with just description' },
    { value: '4', description: 'Fourth description-only option' },
  ];

  return (
    <Select
      label="Description-Only Options"
      value={value}
      onChange={setValue}
      options={descriptionOnlyOptions}
      placeholder="Select by description"
    />
  );
}
```

### Custom styles

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

```jsx live
function CustomStylesExample() {
  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
      label="Single select - styles"
      onChange={setValue}
      options={exampleOptions}
      placeholder="Empty value"
      styles={{
        control: {
          padding: '20px',
          backgroundColor: 'lightgray',
        },
        controlBlendStyles: {
          background: 'coral',
          hoveredBackground: 'crimson',
          pressedBackground: 'red',
        },
        optionBlendStyles: {
          background: 'lightblue',
          hoveredBackground: 'blue',
        },
        dropdown: {
          padding: '20px',
          backgroundColor: 'pink',
        },
      }}
      value={value}
    />
  );
}
```

### Custom class names

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

```jsx
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

If you need to render a custom label (e.g. a label with a tooltip), you can pass a React Node to the `label` prop.

```jsx live
function CustomLabelExample() {
  const [value, setValue] = useState('1');

  const options = [
    { value: '1', label: 'Option 1' },
    { value: '2', label: 'Option 2' },
    { value: '3', label: 'Option 3' },
  ];

  return (
    <Select
      label={
        <HStack alignItems="center" gap={1}>
          Custom Label
          <Tooltip content="This will be visible to other users.">
            <Icon active color="fg" name="info" size="xs" tabIndex={0} />
          </Tooltip>
        </HStack>
      }
      value={value}
      onChange={setValue}
      options={options}
      placeholder="Select an option"
    />
  );
}
```

### Borderless

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

```jsx live
function BorderlessExample() {
  const [singleValue, setSingleValue] = useState('1');
  const { value: multiValue, onChange: multiOnChange } = useMultiSelect({
    initialValue: ['1', '2'],
  });

  const options = [
    { value: '1', label: 'Option 1' },
    { value: '2', label: 'Option 2' },
    { value: '3', label: 'Option 3' },
    { value: '4', label: 'Option 4' },
  ];

  return (
    <VStack gap={4}>
      <Select
        bordered={false}
        label="Borderless single select"
        value={singleValue}
        onChange={setSingleValue}
        options={options}
        placeholder="Select an option"
      />

      <Select
        bordered={false}
        type="multi"
        label="Borderless multi select"
        value={multiValue}
        onChange={multiOnChange}
        options={options}
        placeholder="Select options"
      />
    </VStack>
  );
}
```

### 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.

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

#### Example

```jsx
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}
    />
  );
}
```

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `onChange` | `(value: Type extends multi ? SelectOptionValue \| SelectOptionValue[] \| null : SelectOptionValue \| null) => void` | Yes | `-` | - |
| `options` | `SelectOptionList<Type, SelectOptionValue>` | Yes | `-` | Array of options to display in the select dropdown. Can be individual options or groups with label and options |
| `value` | `string \| SelectOptionValue[] \| null` | Yes | `-` | - |
| `SelectAllOptionComponent` | `SelectOptionComponent<Type, SelectOptionValue>` | No | `-` | Custom component to render the Select All option |
| `SelectControlComponent` | `SelectControlComponent<Type, SelectOptionValue>` | No | `-` | Custom component to render the select control |
| `SelectDropdownComponent` | `SelectDropdownComponent<Type, SelectOptionValue>` | No | `-` | Custom component to render the dropdown container |
| `SelectEmptyDropdownContentsComponent` | `SelectEmptyDropdownContentComponent` | No | `-` | Custom component to render when no options are available |
| `SelectOptionComponent` | `SelectOptionComponent<Type, SelectOptionValue>` | No | `-` | Custom component to render individual options |
| `SelectOptionGroupComponent` | `SelectOptionGroupComponent<Type, SelectOptionValue>` | No | `-` | Custom component to render group headers |
| `accessibilityRoles` | `{ dropdown?: AriaHasPopupType; option?: string \| undefined; } \| undefined` | No | `-` | Accessibility roles for dropdown and option elements |
| `accessory` | `ReactElement<CellAccessoryProps, string \| JSXElementConstructor<any>>` | No | `-` | Accessory element rendered at the end of the cell (e.g., chevron). |
| `bordered` | `boolean` | No | `true` | Add a border around all sides of the box. Determines if the control should have a default border. |
| `className` | `string` | No | `-` | CSS class name for the root element |
| `classNames` | `{ root?: string; control?: string \| undefined; controlStartNode?: string \| undefined; controlInputNode?: string \| undefined; controlValueNode?: string \| undefined; controlLabelNode?: string \| undefined; controlHelperTextNode?: string \| undefined; controlEndNode?: string \| undefined; dropdown?: string \| undefined; option?: string \| undefined; optionCell?: string \| undefined; optionContent?: string \| undefined; optionLabel?: string \| undefined; optionDescription?: string \| undefined; selectAllDivider?: string \| undefined; emptyContentsContainer?: string \| undefined; emptyContentsText?: string \| undefined; optionGroup?: string \| undefined; } \| undefined` | No | `-` | Custom class names for different parts of the select |
| `clearAllLabel` | `string` | No | `-` | Label for the Clear All option in multi-select mode |
| `compact` | `boolean` | No | `-` | Whether to use compact styling for the select |
| `controlAccessibilityLabel` | `string` | No | `-` | Accessibility label for the control |
| `defaultOpen` | `boolean` | No | `-` | Initial open state when component mounts (uncontrolled mode) |
| `disableClickOutsideClose` | `boolean` | No | `-` | Whether clicking outside the dropdown should close it |
| `disabled` | `boolean` | No | `false` | Toggles input interactability and opacity |
| `emptyOptionsLabel` | `string` | No | `-` | Label displayed when there are no options available |
| `end` | `null \| string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal` | No | `-` | End-aligned content (e.g., value, status). Replaces the deprecated detail prop. |
| `endNode` | `null \| string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal` | No | `-` | Adds content to the end of the inner input. Refer to diagram for location of endNode in InputStack component |
| `helperText` | `null \| string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal` | No | `-` | Helper text displayed below the select |
| `hiddenSelectedOptionsLabel` | `string` | No | `-` | Label to show for showcasing count of hidden selected options |
| `hideSelectAll` | `boolean` | No | `-` | Whether to hide the Select All option in multi-select mode |
| `label` | `null \| string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal` | No | `-` | Label displayed above the control |
| `labelVariant` | `inside \| outside` | No | `'outside'` | The variant of the label. Only used when compact is not true. |
| `maxSelectedOptionsToShow` | `number` | No | `-` | Maximum number of selected options to show before truncating |
| `media` | `ReactElement` | No | `-` | Media rendered at the start of the cell (icon, avatar, image, etc). |
| `open` | `boolean` | No | `-` | Controlled open state of the dropdown |
| `placeholder` | `null \| string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal` | No | `-` | Placeholder text displayed when no option is selected |
| `ref` | `null \| (instance: SelectRef \| null) => void \| RefObject<SelectRef>` | No | `-` | - |
| `removeSelectedOptionAccessibilityLabel` | `string` | No | `-` | Accessibility label for each chip in a multi-select |
| `selectAllLabel` | `string` | No | `-` | Label for the Select All option in multi-select mode |
| `setOpen` | `((open: boolean \| ((open: boolean) => boolean)) => void)` | No | `-` | Callback to update the open state |
| `startNode` | `null \| string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal` | No | `-` | Adds content to the start of the inner input. Refer to diagram for location of startNode in InputStack component |
| `style` | `CSSProperties` | No | `-` | Inline styles for the root element |
| `styles` | `{ root?: CSSProperties; control?: CSSProperties \| undefined; controlStartNode?: CSSProperties \| undefined; controlInputNode?: CSSProperties \| undefined; controlValueNode?: CSSProperties \| undefined; controlLabelNode?: CSSProperties \| undefined; controlHelperTextNode?: CSSProperties \| undefined; controlEndNode?: CSSProperties \| undefined; controlBlendStyles?: InteractableBlendStyles \| undefined; dropdown?: CSSProperties \| undefined; option?: CSSProperties \| undefined; optionCell?: CSSProperties \| undefined; optionContent?: CSSProperties \| undefined; optionLabel?: CSSProperties \| undefined; optionDescription?: CSSProperties \| undefined; optionBlendStyles?: InteractableBlendStyles \| undefined; selectAllDivider?: CSSProperties \| undefined; emptyContentsContainer?: CSSProperties \| undefined; emptyContentsText?: CSSProperties \| undefined; optionGroup?: CSSProperties \| undefined; } \| undefined` | No | `-` | Custom styles for different parts of the select |
| `testID` | `string` | No | `-` | Test ID for the root element |
| `type` | `multi \| single` | No | `-` | Whether the select allows single or multiple selections |
| `variant` | `primary \| secondary \| positive \| negative \| foregroundMuted \| foreground` | No | `foregroundMuted` | Determines the sentiment of the input. Because we allow startContent and endContent to be custom ReactNode, the content placed inside these slots will not change colors according to the variant. You will have to add that yourself |