🚨 This component is deprecated

Only use this for reference when working with the existing component. For all new instances, use the Select component.

Default

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

Editable example
() => {
  const [selected, setSelected] = React.useState("");
  const options = ["Octopus", "Cuttlefish", "Squid", "Nautilus"];

  return (
    <Dropdown label="Select a cephalopod" placeholder="Select an option" name={selected}>
      {options.map((option) => (
        <DropdownItem
          key={option}
          name={option}
          onSelect={() => setSelected(option)}
          selected={selected === option}
        />
      ))}
    </Dropdown>
  );
}
() => {
  const [selected, setSelected] = React.useState("");
  const options = ["Octopus", "Cuttlefish", "Squid", "Nautilus"];

  return (
    <Dropdown label="Select a cephalopod" placeholder="Select an option" name={selected}>
      {options.map((option) => (
        <DropdownItem
          key={option}
          name={option}
          onSelect={() => setSelected(option)}
          selected={selected === option}
        />
      ))}
    </Dropdown>
  );
}

Best practices

1. Use with four or more options. For fewer options, or when the options have very short labels, consider using a SegmentedControl.
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 OptionMenu.

Sizes

Like with all controls, match the sizing of the Dropdown 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 [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 (
    <>
      <Dropdown label="Small" placeholder="Select an option" name={small} size={DropdownSize.Small}>
        {options.map((option) => (
          <DropdownItem
            key={option}
            name={option}
            onSelect={() => setSmall(option)}
            selected={small === option}
          />
        ))}
      </Dropdown>
      <Dropdown label="Medium" placeholder="Select an option" name={medium} size={DropdownSize.Medium}>
        {options.map((option) => (
          <DropdownItem
            key={option}
            name={option}
            onSelect={() => setMedium(option)}
            selected={medium === option}
          />
        ))}
      </Dropdown>
      <Dropdown label="Large" placeholder="Select an option" name={large} size={DropdownSize.Large}>
        {options.map((option) => (
          <DropdownItem
            key={option}
            name={option}
            onSelect={() => setLarge(option)}
            selected={large === option}
          />
        ))}
      </Dropdown>
    </>
  );
}
() => {
  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 (
    <>
      <Dropdown label="Small" placeholder="Select an option" name={small} size={DropdownSize.Small}>
        {options.map((option) => (
          <DropdownItem
            key={option}
            name={option}
            onSelect={() => setSmall(option)}
            selected={small === option}
          />
        ))}
      </Dropdown>
      <Dropdown label="Medium" placeholder="Select an option" name={medium} size={DropdownSize.Medium}>
        {options.map((option) => (
          <DropdownItem
            key={option}
            name={option}
            onSelect={() => setMedium(option)}
            selected={medium === option}
          />
        ))}
      </Dropdown>
      <Dropdown label="Large" placeholder="Select an option" name={large} size={DropdownSize.Large}>
        {options.map((option) => (
          <DropdownItem
            key={option}
            name={option}
            onSelect={() => setLarge(option)}
            selected={large === option}
          />
        ))}
      </Dropdown>
    </>
  );
}

Multi select

When allowing multiple selection, the remainOpenOnSelect prop should be used to prevent the menu closing when an option is selected.

Editable example
() => {
  const [selected, setSelected] = React.useState([]);
  const options = ["Octopus", "Cuttlefish", "Squid", "Nautilus"];

  const getName = () => {
    if (selected.length === 0) return;
    if (selected.length === 1) return selected[0];
    return `${selected.length} options selected`;
  }

  return (
    <Dropdown
      remainOpenOnSelect
      label="Select a cephalopod"
      placeholder="Select one or more options"
      name={getName()}
    >
      {options.map((option) => (
        <DropdownItem
          key={option}
          name={option}
          onSelect={() => {
            if (selected.includes(option)) {
              setSelected(selected.filter((item) => item !== option));
            } else {
              setSelected([...selected, option])
            }
          }}
          selected={selected.includes(option)}
        />
      ))}
    </Dropdown>
  );
}
() => {
  const [selected, setSelected] = React.useState([]);
  const options = ["Octopus", "Cuttlefish", "Squid", "Nautilus"];

  const getName = () => {
    if (selected.length === 0) return;
    if (selected.length === 1) return selected[0];
    return `${selected.length} options selected`;
  }

  return (
    <Dropdown
      remainOpenOnSelect
      label="Select a cephalopod"
      placeholder="Select one or more options"
      name={getName()}
    >
      {options.map((option) => (
        <DropdownItem
          key={option}
          name={option}
          onSelect={() => {
            if (selected.includes(option)) {
              setSelected(selected.filter((item) => item !== option));
            } else {
              setSelected([...selected, option])
            }
          }}
          selected={selected.includes(option)}
        />
      ))}
    </Dropdown>
  );
}

Long labels

Use the hasLongLabel prop to change the label styling to be more readable for longer labels.

Editable example
() => {
  const [selected, setSelected] = React.useState("");
  const options = ["Octopus", "Cuttlefish", "Squid", "Nautilus"];

  return (
    <Dropdown hasLongLabel label="A really long label that is hard to read in all-caps" placeholder="Select an option" name={selected}>
      {options.map((option) => (
        <DropdownItem
          key={option}
          name={option}
          onSelect={() => setSelected(option)}
          selected={selected === option}
        />
      ))}
    </Dropdown>
  );
}
() => {
  const [selected, setSelected] = React.useState("");
  const options = ["Octopus", "Cuttlefish", "Squid", "Nautilus"];

  return (
    <Dropdown hasLongLabel label="A really long label that is hard to read in all-caps" placeholder="Select an option" name={selected}>
      {options.map((option) => (
        <DropdownItem
          key={option}
          name={option}
          onSelect={() => setSelected(option)}
          selected={selected === option}
        />
      ))}
    </Dropdown>
  );
}

Theme

Control the theme by passing the theme prop a DropdownTheme enum option.

Editable example
() => {
  const [selected, setSelected] = React.useState("");
  const options = ["Octopus", "Cuttlefish", "Squid", "Nautilus"];

  return (
    <Card theme={CardTheme.Dark}>
      <div className="space-inset-m">
        <Dropdown label="Dark dropdown 😎" placeholder="Select an option" name={selected} theme={DropdownTheme.Dark}>
          {options.map((option) => (
            <DropdownItem
              key={option}
              name={option}
              onSelect={() => setSelected(option)}
              selected={selected === option}
            />
          ))}
        </Dropdown>
      </div>
    </Card>
  );
}
() => {
  const [selected, setSelected] = React.useState("");
  const options = ["Octopus", "Cuttlefish", "Squid", "Nautilus"];

  return (
    <Card theme={CardTheme.Dark}>
      <div className="space-inset-m">
        <Dropdown label="Dark dropdown 😎" placeholder="Select an option" name={selected} theme={DropdownTheme.Dark}>
          {options.map((option) => (
            <DropdownItem
              key={option}
              name={option}
              onSelect={() => setSelected(option)}
              selected={selected === option}
            />
          ))}
        </Dropdown>
      </div>
    </Card>
  );
}

Accessibility

This component has not been updated to meet WCAC AA accessibility.