The SelectMenu shares most of its behaviour, appearance and API with the DropdownMenu. Rather than accepting children you must provide options as an array, an onChange handler and a value.

Alternatives

Dropdown — For presenting a list of discrete actions to a user

Standard

Single select

The single select is used for setting enumerable values when filtering data. It is not to be used in forms, where an actual input element is required; prefer the SelectField.

Edit in Playroom

const options = ['Chocolate', 'Vanilla', 'Strawberry'].map((label) => ({
  label,
  value: label.toLowerCase(),
}));
const [selected, setSelected] = useState();
const triggerLabel = 'Flavour' + (selected ? `: ${selected.label}` : '');
return (
  <SelectMenu
    trigger={triggerLabel}
    onChange={setSelected}
    options={options}
    value={selected}
  />
);

Multi select

The SelectMenu is unopinionated in how many items are selected in the list, or how you manage selected options. Pass an array to the value prop to select more items.

Edit in Playroom

const options = ['Chocolate', 'Vanilla', 'Strawberry'].map((label) => ({
  label,
  value: label.toLowerCase(),
}));
const [selected, setSelected] = useState([]);
const handleChange = (item) => {
  const some = (opt) => opt.value === item.value;
  const none = (opt) => opt.value !== item.value;
  if (selected.some(some)) {
    setSelected((old) => old.filter(none));
  } else {
    setSelected((old) => old.concat(item));
  }
};
const selectedLabel = selected.map((opt) => opt.label).join(', ');
const triggerLabel = 'Flavour' + (selected.length ? `: ${selectedLabel}` : '');
return (
  <SelectMenu
    trigger={triggerLabel}
    onChange={handleChange}
    options={options}
    value={selected}
  />
);

Disabled option

You may disable options where appropriate.

Edit in Playroom

const options = ['Chocolate', 'Vanilla', 'Strawberry'].map((label, index) => ({
  label,
  value: label.toLowerCase(),
  disabled: index === 2,
}));
const [selected, setSelected] = useState();
const triggerLabel = 'Flavour' + (selected ? `: ${selected.label}` : '');
return (
  <SelectMenu
    trigger={triggerLabel}
    onChange={setSelected}
    options={options}
    value={selected}
  />
);

Filterable

Allow the users to search for items within the menu. We recommend only introducing filter behaviour when the expected option count is greater than 6.

The FilterMenu shares most of the SelectMenu API, with a few additions to manage filtering -- checkout the API tab to learn more.

Edit in Playroom

const fruits = [
  'Apple',
  'Banana',
  'Cherry',
  'Lemon',
  'Mango',
  'Nectarine',
  'Orange',
  'Peach',
  'Raspberry',
  'Strawberry',
  'Watermelon',
];
const labelToOption = (label) => ({ label, value: label });
const compare = (a, b) => a.toLowerCase().includes(b?.toLowerCase());
const [selected, setSelected] = useState();
const [options, setOptions] = useState(fruits.map(labelToOption));
const triggerLabel = 'Flavour' + (selected ? `: ${selected.label}` : '');
const onInputChange = (input) => {
  setOptions(
    fruits.filter((label) => compare(label, input)).map(labelToOption)
  );
};
return (
  <FilterMenu
    onChange={setSelected}
    onInputChange={onInputChange}
    options={options}
    trigger={triggerLabel}
    value={selected}
  />
);

Async

The FilterMenu has no opinions about how you filter the options, whether it's client or server side. If you fetch options onInputChange, you must show the user that it isLoading. We recommend using debounce (or similar) to optimise performance.

Edit in Playroom

const labelToOption = (label) => ({ label, value: label });
const compare = (a, b) => a.toLowerCase().includes(b?.toLowerCase());
const [selected, setSelected] = useState();
const [loading, setLoading] = useState(false);
const [options, setOptions] = useState([]);
const triggerLabel = 'Fruit' + (selected ? `: ${selected.label}` : '');
// handle input change
let sleep = (ms) => new Promise((r) => setTimeout(r, ms));
async function onInputChange(input) {
  if (!input) {
    setOptions([]);
    return;
  }
  setLoading(true);
  await sleep(Math.random() * 1000);
  let res = [
    'Apple',
    'Banana',
    'Cherry',
    'Lemon',
    'Mango',
    'Nectarine',
    'Orange',
    'Peach',
    'Raspberry',
    'Strawberry',
    'Watermelon',
  ].filter((label) => compare(label, input));
  setOptions(res.map(labelToOption));
  setLoading(false);
}
return (
  <FilterMenu
    placeholder="Type to search"
    isLoading={loading}
    onChange={setSelected}
    onInputChange={onInputChange}
    options={options}
    trigger={triggerLabel}
    value={selected}
  />
);

Receipes

Mapping

Provide alternative properties in your options using the itemToDisabled, itemToValue, and itemToLabel utilities. Map complex objects to the required data select-menu requires while using other properties in the itemRenderer.

Edit in Playroom

const [selected, setSelected] = useState();
const [loading, setLoading] = useState(false);
const [options, setOptions] = useState([]);
React.useEffect(() => {
  const doFetch = async () => {
    let res = await fetch('https://hp-api.herokuapp.com/api/characters');
    let characters = await res.json();
    setOptions(characters.filter((c) => c.house && c.dateOfBirth));
  };
  doFetch();
}, []);
const triggerLabel = 'Character' + (selected ? `: ${selected.name}` : '');
const toDisabled = (i) => i.name === 'Lord Voldemort';
return (
  <SelectMenu
    itemToDisabled={toDisabled}
    itemToLabel={(i) => i.name}
    itemToValue={(i) => i.dateOfBirth}
    onChange={setSelected}
    options={options}
    trigger={triggerLabel}
    value={selected}
    itemRenderer={(i) => (
      <div style={{ opacity: toDisabled(i) ? 0.5 : 1 }}>
        <Text size="small" weight="medium">
          {i.name}
        </Text>
        <Text size="xsmall" color="muted">
          {i.house} {i.hogwartsStaff ? '(teacher)' : null}
        </Text>
      </div>
    )}
  />
);

Item renderer

You can provide an alternate item renderer.

Edit in Playroom

const statuses = [
  'Neutral',
  'Informative',
  'Accent',
  'Critical',
  'Positive',
].map((label) => ({ label, value: label.toLowerCase() }));
const users = [
  'Tim Wilson',
  'Alex Lee',
  'Jason Smith',
  'Mia Walker',
  'Richie Chung',
];
const identity = (i) => i;
const [status, setStatus] = useState();
const [user, setUser] = useState();
const statusLabel = 'Status' + (status ? `: ${status.label}` : '');
const userLabel = 'User' + (user ? `: ${user}` : '');
return (
  <Inline gap="medium">
    <SelectMenu
      itemRenderer={(item) => <Badge tone={item.value} label={item.label} />}
      trigger={statusLabel}
      onChange={setStatus}
      options={statuses}
      value={status}
    />
    <SelectMenu
      itemRenderer={(item) => (
        <Inline alignY="center" gap="medium">
          <UserAvatar size="xsmall" name={item} />
          <span>{item}</span>
        </Inline>
      )}
      trigger={userLabel}
      onChange={setUser}
      options={users}
      itemToLabel={identity}
      itemToValue={identity}
      value={user}
    />
  </Inline>
);

itemHeight

Used in conjunction with itemRenderer to achieve custom layouts.

Default is 40

Clearable value

Provide onClear in addition to the onChange handler to let the user clear all the values with one click.

Edit in Playroom

const flavours = ['Chocolate', 'Vanilla', 'Strawberry', 'Caramel', 'Mint'];
const [selected, setSelected] = useState([]);
const handleChange = (flavour) => {
  if (selected.includes(flavour)) {
    setSelected((old) => old.filter((opt) => opt !== flavour));
  } else {
    setSelected((old) => old.concat(flavour));
  }
};
const handleClear = () => {
  setSelected([]);
};
const triggerLabel =
  'Flavour' + (selected.length ? `: ${selected.join(', ')}` : '');
return (
  <SelectMenu
    trigger={triggerLabel}
    onChange={handleChange}
    onClear={handleClear}
    options={flavours}
    itemToLabel={(i) => i}
    itemToValue={(i) => i}
    value={selected}
  />
);

Labelling

There's a few strategies for displaying the value within the button.

Verbose

The most user friendly approach is to display as much information as possible to the user within your space constraints. In the example below we show up to 2 values, then when there's more than two we show the first selected value and the remaining count.

Edit in Playroom

const labels = ['Chocolate', 'Vanilla', 'Strawberry', 'Caramel', 'Mint'];
const [selected, setSelected] = useState([]);
const handleChange = (item) => {
  const some = (opt) => opt.value === item.value;
  const none = (opt) => opt.value !== item.value;
  if (selected.some(some)) {
    setSelected((old) => old.filter(none));
  } else {
    setSelected((old) => old.concat(item));
  }
};
const selectedLabels = selected.map((i) => i.label);
const selectedCount = selectedLabels.length;
const triggerSuffix =
  selectedCount > 2
    ? `${selectedLabels[0]} +${selectedCount - 1} more`
    : selectedLabels.join(', ');
const triggerLabel = 'Flavour' + (triggerSuffix ? ': ' : '') + triggerSuffix;
return (
  <SelectMenu
    trigger={triggerLabel}
    onChange={handleChange}
    options={labels.map((label, value) => ({ label, value }))}
    value={selected}
  />
);

Highlight

You may want to highlight the selected value through font-weight and/or colour.

Edit in Playroom

const options = ['Chocolate', 'Vanilla', 'Strawberry', 'Caramel', 'Mint'];
const [selected, setSelected] = useState(options[2]);
const triggerLabel = (
  <>
    <Text leading="tighter" size="small" color="muted">
      Flavour:&nbsp;
    </Text>
    <Text leading="tighter" size="small" weight="medium" color="active">
      {selected}
    </Text>
  </>
);
return (
  <SelectMenu
    trigger={triggerLabel}
    onChange={setSelected}
    options={options}
    itemToLabel={(i) => i}
    itemToValue={(i) => i}
    value={selected}
  />
);

Indicator

When horizontal space is at a premium you may want to display the count in a notification badge.

Edit in Playroom

const flavours = ['Chocolate', 'Vanilla', 'Strawberry', 'Caramel', 'Mint'];
const [selected, setSelected] = useState(flavours.slice(0, 1));
const identity = (i) => i;
const negate = (predicate) => (...args) => !predicate(...args);
const handleChange = (compare) => {
  const some = (item) => item === compare;
  const none = negate(some);
  if (selected.some(some)) {
    setSelected((old) => old.filter(none));
  } else {
    setSelected((old) => old.concat(compare));
  }
};
const badge = <NotificationBadge tone="informative" value={selected.length} />;
const triggerLabel = (
  <Inline gap="xsmall">
    <Text>Flavour</Text>
    {selected.length ? badge : null}
  </Inline>
);
return (
  <SelectMenu
    trigger={triggerLabel}
    onChange={handleChange}
    options={flavours}
    itemToLabel={identity}
    itemToValue={identity}
    value={selected}
  />
);

Pagination

SelectMenu can be used in a paginated mode using the infinite scrolling technique.

To use pagination you must provied the following props:

canLoadMore — signal that more items are available
onLoadMore — function to load more items when user reaches the bottom of the menu and canLoadMore is true
loadingState — must be kept in-sync to avoid duplicate calls

NOTE: Like all handlers, onLoadMore must be memoized with React.useCallback() for performance.

Edit in Playroom

const kantoList = useFetchPokemon();
  const [paginatedItems, setPaginatedItems] = useState(kantoList.slice(0, 10));
  const itemToLabel = React.useCallback((item: PokemonItemType) => {
    return item.name;
  }, []);
  const itemToValue = React.useCallback((item: PokemonItemType) => {
    return item.id;
  }, []);
  const [selected, setSelected] = useState<PokemonItemType | undefined>();
  const [loadingState, setLoadingState] = useState<
    SelectMenuProps<any>['loadingState']
  >('loading');
  const triggerLabel = ({
    isOpen,
    triggerProps,
  }: {
    isOpen: boolean;
    triggerProps: ButtonHTMLAttributes<HTMLButtonElement>;
  }) => {
    const { children, ..._triggerProps } = triggerProps;
    return (
      <ActionButton
        label={'Pokemon' + (selected ? `: ${selected.name}` : '')}
        iconAfter={isOpen ? ChevronUpIcon : ChevronDownIcon}
        {..._triggerProps}
      />
    );
  };
  const canLoadMore = paginatedItems.length < kantoList.length;
  // handle input change
  let sleep = (ms: number) => {
    return new Promise((r) => {
      return setTimeout(r, ms);
    });
  };
  const onLoadMore = React.useCallback(async () => {
    setLoadingState('loadingMore');
    await sleep(Math.random() * 2000);
    setPaginatedItems((curr) => {
      return kantoList.slice(0, curr.length + 20);
    });
    setLoadingState('idle');
  }, [kantoList]);
  return (
    <Stack gap="medium">
      <Text>
        {paginatedItems.length} items loaded, {canLoadMore ? '' : 'no'} more
        available
      </Text>
      <Text>
      loadingState: {loadingState}
      </Text>
      <SelectMenu
        loadingState={loadingState}
        onLoadMore={onLoadMore}
        onChange={setSelected}
        options={paginatedItems}
        itemToLabel={itemToLabel}
        itemToValue={itemToValue}
        trigger={triggerLabel}
        value={selected}
        canLoadMore={canLoadMore}
      />
    </Stack>
  );
type PokemonItemType = {
  name: string;
  imageSource: string;
  id: string;
  types: string[];
};
function titleCase(str: string) {
  return str[0].toUpperCase() + str.substring(1).toLowerCase();
}
function useFetchPokemon(limit = 151) {
  const [statefulList, setStatefulList] = useState<PokemonItemType[]>([]);
  React.useEffect(() => {
    const { abort, signal } = new AbortController();
    async function fetchDetails(pokemon: {
      url: string;
    }): Promise<PokemonItemType> {
      const response = await fetch(pokemon.url);
      const json = await response.json();
      // resolve and limit complex data before passing on
      return {
        name: titleCase(json.name),
        imageSource: json?.sprites?.front_default,
        id: json.id,
        types: json.types.map((t: { type: { name: string } }) => {
          return titleCase(t.type.name);
        }),
      };
    }
    async function fetchAll() {
      const response = await fetch(
        `https://pokeapi.co/api/v2/pokemon?limit=${limit}`,
        { signal }
      );
      const json = await response.json();
      const list: PokemonItemType[] = await Promise.all(
        json.results.map(fetchDetails)
      );
      if (!signal.aborted) {
        setStatefulList(list);
      }
    }
    try {
      fetchAll();
    } catch (error) {
      console.error('fetch failed');
    }
    return () => {
      abort();
    };
  }, [limit]);
  return statefulList;
}

Select Menu

Standard

Single select

Multi select

Disabled option

Filterable

Async

Receipes

Mapping

Item renderer

itemHeight

Clearable value

Labelling

Verbose

Highlight

Indicator

Pagination