<Notice>
  <Text>
    If you're building a form and need a select, prefer using the{' '}
    <Link label="SelectInput" href="/packages/select-input" /> as it supports the FieldContext.
  </Text>
</Notice>

## Usage

Use the `<SelectDropdown />` component when the user needs to choose a single or multiple options from a group of options, and horizontal space is limited. The most common implementation is when building an experience to filter large sets of data.

## Label

The SelectDropdown comes with a default trigger button when you pass the `label` prop. On selection, it will automatically display the selected value inside the button label. This is the most common and easiest way of implementing the SelectDropdown.

```tsx live
type Item = { label: string; value: string };
const [selected, setSelected] = useState<Item | null>();

const handleChange = (item: Item | null) => {
  setSelected(item);
};

return (
  <SelectDropdown
    label="Country"
    value={selected}
    onChange={handleChange}
    items={[
      { label: 'Australia', value: 'au' },
      { label: 'Canada', value: 'ca' },
      { label: 'New Zealand', value: 'nz' },
      { label: 'United States of America', value: 'us' },
      { label: 'Sweden', value: 'se' },
    ]}
  />
);
```

Optionally, a [custom trigger](#custom-trigger) component can be passed via the `trigger` prop.

## Multi-select

The `<SelectDropdown />` component can also be used for multiple options selection by passing in the `isMulti` prop. Instead of using the `onChange` prop, use `onChangeMulti` to handle the selected items. The `value` prop should be an array of selected items.

NOTE: If using the `label` prop, the trigger button will display the selected value for a single selection, e.g. "Australia" in the example below, and multiple selected values as "X selected" etc.

```tsx live
type Item = { label: string; value: string };
const [selected, setSelected] = useState<Item[]>([]);

const handleChange = (value: Item[] | null) => {
  setSelected(value ?? []);
};

return (
  <Flex flexDirection="column">
    <Box>
      <SelectDropdown
        isMulti
        label="Countries"
        value={selected}
        onChangeMulti={handleChange}
        items={React.useMemo(
          () => [
            { label: 'Australia', value: 'au' },
            { label: 'Canada', value: 'ca' },
            { label: 'New Zealand', value: 'nz' },
            { label: 'United States of America', value: 'us' },
            { label: 'Sweden', value: 'se' },
          ],
          []
        )}
      />
    </Box>

    <ResponseBlock prefix="Selected:" value={JSON.stringify(selected)} />
  </Flex>
);
```

## Hiding the search input

The search input inside the dropdown can be hidden by setting the `hideSearchInput` prop to `true`. This is useful when the list of items is short and the user can easily find the item they are looking for.

```tsx live
type Item = { label: string; value: string };
const [selected, setSelected] = useState<Item | null>();

const handleChange = (item: Item | null) => {
  setSelected(item);
};

return (
  <SelectDropdown
    hideSearchInput
    label="Country"
    value={selected}
    onChange={handleChange}
    items={[
      { label: 'Australia', value: 'au' },
      { label: 'Canada', value: 'ca' },
      { label: 'New Zealand', value: 'nz' },
      { label: 'United States of America', value: 'us' },
      { label: 'Sweden', value: 'se' },
    ]}
  />
);
```

## Clear button

A clear button can be added to the dropdown by passing in the `clearButton` prop. Clearing the selected option(s) closes the dropdown list immediately.

```tsx live
type Item = {
  label: string;
  value: string;
};

const [singleSelect, setSingleSelect] = useState<Item | null>();
const [multiSelect, setMultiSelect] = useState<Item[] | null>([]);

const items = React.useMemo(
  () => [
    { label: 'Australia', value: 'au' },
    { label: 'Canada', value: 'ca' },
    { label: 'New Zealand', value: 'nz' },
    { label: 'United States of America', value: 'us' },
    { label: 'Sweden', value: 'se' },
  ],
  []
);

const handleMultiChange = (value: Item[] | null) => {
  setMultiSelect(value);
};

const handleSingleChange = (value: Item | null) => {
  setSingleSelect(value);
};

return (
  <>
    <Flex gap="small">
      <SelectDropdown
        clearButton
        label="Multi-select"
        value={multiSelect}
        isMulti
        onChangeMulti={handleMultiChange}
        items={items}
      />
      <SelectDropdown
        clearButton
        label="Single-select"
        value={singleSelect}
        onChange={handleSingleChange}
        items={items}
      />
    </Flex>

    <Flex flexDirection="column">
      <ResponseBlock prefix="Multi-selected:" value={multiSelect !== null ? JSON.stringify(multiSelect) : undefined} />
      <ResponseBlock
        prefix="Single-selected:"
        value={singleSelect !== null ? JSON.stringify(singleSelect) : undefined}
      />
    </Flex>
  </>
);
```

## Disabled items

If you need to disable an item in the dropdown list, you can add `isDisabled: true` to the item object.

```tsx live
type Item = { label: string; value: string };
const [selected, setSelected] = useState<Item | null>();

const handleChange = (item: Item | null) => {
  setSelected(item);
};

return (
  <SelectDropdown
    hideSearchInput
    label="Country"
    value={selected}
    onChange={handleChange}
    items={[
      { label: 'Australia', value: 'au' },
      { label: 'Canada', value: 'ca', isDisabled: true },
      { label: 'New Zealand', value: 'nz' },
      { label: 'United States of America', value: 'us' },
      { label: 'Sweden', value: 'se' },
    ]}
  />
);
```

## Custom trigger

A custom trigger component can be passed via the `trigger` prop. This can be any HTML button element, but it's recommended to use either `<Button />` or `<AdornmentButton />` for consistency and the best user experience. You have to pass on [ref](#ref) for positioning to work, and can also opt to pass the dropdown's [open state](#open-state) to your trigger button.

NOTE: You can not use the `label` prop and the `trigger` prop at the same time.

```tsx live
type Item = { label: string; value: string };
const [selected, setSelected] = useState<Item | null>();

const handleChange = (item: Item | null) => {
  setSelected(item);
};

return (
  <Flex flexDirection="column">
    <Box>
      <SelectDropdown
        trigger={(ref, isOpen) => (
          <Button
            ref={ref}
            icon={isOpen ? ChevronUpIcon : ChevronDownIcon}
            iconOnly
            label="Select a country"
            size="small"
            tone="neutral"
          />
        )}
        value={selected}
        onChange={handleChange}
        items={[
          { label: 'Australia', value: 'au' },
          { label: 'Canada', value: 'ca' },
          { label: 'New Zealand', value: 'nz' },
          { label: 'United States of America', value: 'us' },
          { label: 'Sweden', value: 'se' },
        ]}
      />
    </Box>

    <ResponseBlock prefix="Selected:" value={JSON.stringify(selected)} />
  </Flex>
);
```

### Ref

The opening and closing of the dropdown relies on `ref` being passed to your button element. The `ref` itself is created and owned locally by the component, using a render-prop API. All you need to do is pass it on in a callback function to your trigger component.

### Open state

The render-prop API of the trigger also gives you a second argument (boolean), to hook in to the open state of the dropdown. This can be useful if you need to conditionally switch a chevron icon, for example.

## Dropdown positioning

### Side

The `side` prop is used to define the position of the dropdown. The supported values are: `"top" | "right" | "bottom" | "left"`. Defaults to `bottom`.

### Align

The `align` prop is used to define the alignment of the dropdown. The supported values are: `"start" | "center" | "end"`. Defaults to `start`.

## Other props

In addition, the `<SelectDropdown />` supports most of the [SelectInput](/packages/select-input/) props.

A dropdown control that allows the user to make selections from a list of values.

SelectDropdown

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AddressInput

AppLayout

Avatar

Badge

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Checkbox

Core

DateDropdown

DateInput

Divider

EmptyState

Field

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Modal

Notice

PageHeader

Pagination

PhoneInput

Popover

Radio

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Toggle

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources