Alternatives

Autocomplete — Presents a filtered list only when the user has provided input. For extremely large datasets, where browsing the complete list would be inappropriate.
SelectInput — For small lists.

Usage

The Combobox is a controlled component. You "own" the state, which is managed by providing handlers to the component.

NOTE: All handlers must be memoized with React.useCallback() for performance.

NOTE: Pass the window object to the environment prop in Storybook (or when using inside an iframe) to prevent interaction issues.

Basic

The following props are required:

inputValue — The input value
items — The array of items for the user to select from
onChange — Handle changes to the selected item
onInputChange — Handle changes to the input value
value — The selected item

Edit in Playroom

const itemData = React.useMemo(
  () => [
    { label: 'Chocolate', value: 'chocolate' },
    { label: 'Vanilla', value: 'vanilla' },
    { label: 'Strawberry', value: 'strawberry' },
  ],
  []
);
// prepare internal state, which will be passed to the component
const [inputValue, setInputValue] = useState('');
const [items, setItems] = useState(itemData);
const [selectedItem, setSelectedItem] = useState(null);
// NOTE: memoize handlers before providing to the component
const onInputChange = React.useCallback(
  (text) => {
    // sync the user input with your state
    setInputValue(text);
    // filter your items based on user input
    setItems(() => {
      if (text) {
        return itemData.filter(({ label }) =>
          label.toLowerCase().includes(text.toLowerCase())
        );
      }
      // if no input is available (e.g. '') return the default set of items
      return itemData;
    });
  },
  [itemData]
);
return (
  <Field label="Basic example">
    <Combobox
      placeholder="Select an item"
      inputValue={inputValue}
      items={items}
      onChange={setSelectedItem}
      onInputChange={onInputChange}
      value={selectedItem}
    />
  </Field>
);

Clear

Optionally provide an onClear handler, allowing users to "clear" their selection.

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

Edit in Playroom

const itemData = React.useMemo(
  () => [
    { label: 'Chocolate', value: 'chocolate' },
    { label: 'Vanilla', value: 'vanilla' },
    { label: 'Strawberry', value: 'strawberry' },
  ],
  []
);
const [inputValue, setInputValue] = useState('');
const [items, setItems] = useState(itemData);
const [selectedItem, setSelectedItem] = useState(null);
// NOTE: memoize handlers before providing to the component
const onClear = React.useCallback(() => {
  // reset the input value
  setInputValue('');
  // reset the items
  setItems(itemData);
  // reset the selected item
  setSelectedItem(null);
}, [itemData]);
const onInputChange = React.useCallback(
  (text) => {
    setInputValue(text);
    setItems(() => {
      if (text) {
        return itemData.filter(({ label }) =>
          label.toLowerCase().includes(text.toLowerCase())
        );
      }
      return itemData;
    });
  },
  [itemData]
);
return (
  <Field label="Clearable example">
    <Combobox
      placeholder="Select an item to show clear action"
      inputValue={inputValue}
      items={items}
      onChange={setSelectedItem}
      onClear={onClear}
      onInputChange={onInputChange}
      value={selectedItem}
    />
  </Field>
);

Data shape

By default the Combobox assumes that items will take the following shape:

type Item = {
  label: string;
  value: string | number;
  disabled?: boolean;
};

However, if your items have a different shape, you can provide "transform" functions to let the Combobox know how to handle your data:

itemToDisabled
itemToLabel
itemToValue

NOTE: All "transform" functions must be memoized with React.useCallback() for performance.

Edit in Playroom

const itemData = React.useMemo(
  () => [
    {
      name: 'Belgian Chocolate',
      id: '3746856f-13b1-41f8-810d-1d932342c5dd',
      score: 9,
    },
    {
      name: 'Vanilla Bean',
      id: '57f74719-da2c-4eec-a73a-80ec8f8dea94',
      score: 4,
    },
    {
      name: 'Strawberries & Cream',
      id: '5a66d5a1-66f4-483b-ba9b-59c542f5cca2',
      score: 7,
    },
  ],
  []
);
const [items, setItems] = useState(itemData);
const [selectedItem, setSelectedItem] = useState(null);
const [inputValue, setInputValue] = useState('');
// NOTE: memoize functions before providing to the component
const itemToDisabled = React.useCallback((item) => item.score < 5, []);
const itemToLabel = React.useCallback((item) => item.name, []);
const itemToValue = React.useCallback((item) => item.id, []);
const onInputChange = React.useCallback(
  (text) => {
    setInputValue(text);
    setItems(() => {
      if (text) {
        return itemData.filter(({ name }) =>
          name.toLowerCase().includes(text.toLowerCase())
        );
      }
      return itemData;
    });
  },
  [itemData]
);
return (
  <Field label="Data shape example">
    <Combobox
      // transform functions
      itemToDisabled={itemToDisabled}
      itemToLabel={itemToLabel}
      itemToValue={itemToValue}
      // business as usual
      placeholder="Select"
      items={items}
      onInputChange={onInputChange}
      inputValue={inputValue}
      onChange={setSelectedItem}
      value={selectedItem}
    />
  </Field>
);

Appearance

For brevity, search and selection are not implemented in the "appearance" examples.

Disabled

When "disabled" the Combobox will not be interactive and take on a dim appearance.

Edit in Playroom

<Field label="Disabled example">
  <Combobox disabled inputValue="Not interactive" items={[]} />
</Field>

Invalid

When the parent Field has an "invalidMessage" the Combobox controls will take on a "critical" appearance.

Edit in Playroom

<Field label="Invalid example" invalidMessage="Required field">
  <Combobox
    inputValue=""
    onInputChange={() => {}}
    onChange={() => {}}
    items={[
      { label: 'Chocolate', value: 'chocolate' },
      { label: 'Vanilla', value: 'vanilla' },
      { label: 'Strawberry', value: 'strawberry' },
    ]}
  />
</Field>

Size

The Combobox suppports a size property, which influences the input controls and the default item height. For dense interfaces where screen reale state is limited you may want to use the "small" size.

Edit in Playroom

<Field label="Small example">
  <Combobox
    size="small"
    inputValue=""
    onInputChange={() => {}}
    onChange={() => {}}
    value={{ label: 'Chocolate', value: 'chocolate' }}
    items={[
      { label: 'Chocolate', value: 'chocolate' },
      { label: 'Vanilla', value: 'vanilla' },
      { label: 'Strawberry', value: 'strawberry' },
    ]}
  />
</Field>

Placeholder

The text that appears in the form control when it has no value set.

Edit in Playroom

<Field label="Placeholder example">
  <Combobox
    placeholder="Placeholder text"
    inputValue=""
    onInputChange={() => {}}
    onChange={() => {}}
    items={[
      { label: 'Chocolate', value: 'chocolate' },
      { label: 'Vanilla', value: 'vanilla' },
      { label: 'Strawberry', value: 'strawberry' },
    ]}
  />
</Field>

Custom item

To display a custom item you can provide an itemRenderer to the combobox.

NOTE: Should be a pure function (no side-effects), declared outside of the component.

Edit in Playroom

// DOCS ONLY — declare this function ouside of your component
const itemRenderer = React.useCallback(({ label }) => {
  return (
    <Flex gap="small" alignItems="center">
      <UserAvatar name={label} size="xsmall" />
      <Text>{label}</Text>
    </Flex>
  );
}, []);
return (
  <Field label="Custom item example">
    <Combobox
      itemRenderer={itemRenderer}
      inputValue=""
      onInputChange={() => {}}
      onChange={() => {}}
      items={[
        { label: 'Chocolate', value: 'chocolate' },
        { label: 'Vanilla', value: 'vanilla' },
        { label: 'Strawberry', value: 'strawberry' },
      ]}
    />
  </Field>
);

Item height

Because the scroll menu is virtualized we need an itemHeight (in pixels) to safely render the list. You only need to provide an itemHeight when using a custom itemRenderer and the height of your items differs from the default item implementation.

Edit in Playroom

// DOCS ONLY — declare this function ouside of your component
const itemRenderer = React.useCallback(({ label }) => {
  return (
    <Flex gap="small" alignItems="center">
      <UserAvatar name={label} size="small" />
      <Stack>
        <Text>{label}</Text>
        <Text weight="regular" color="muted">
          Ice cream flavour
        </Text>
      </Stack>
    </Flex>
  );
}, []);
return (
  <Field label="Item height example">
    <Combobox
      itemRenderer={itemRenderer}
      itemHeight={48}
      // standard props
      inputValue=""
      onInputChange={() => {}}
      onChange={() => {}}
      items={[
        { label: 'Chocolate', value: 'chocolate' },
        { label: 'Vanilla', value: 'vanilla' },
        { label: 'Strawberry', value: 'strawberry' },
      ]}
    />
  </Field>
);

By default, the menu dialog will match the width of the input container. For situations where horizontal real estate is limited this might mean that menu items are clipped. Provide a menuWidth prop to resolve the issue, accomodating expected item label lengths.

Edit in Playroom

return (
  <Box width={150}>
    <Field label="Menu items not cutoff ">
      <Combobox
        menuWidth={200}
        // standard props
        inputValue=""
        onInputChange={() => {}}
        onChange={() => {}}
        items={[
          { label: 'Yummy Chocolate', value: 'chocolate' },
          { label: 'Sweet Vanilla', value: 'vanilla' },
          { label: 'Amazing Strawberry', value: 'strawberry' },
        ]}
      />
    </Field>
  </Box>
);

Async

The logic for filtering items typically lives on the server rather than the client because it’s impractical to send all possible items over the network. However, when prototyping in Playroom or working with smaller datasets, you may want to perform this filtering on the client instead.

The async examples simulate a server request using the simulateFetch utility. You should not use this in your application.

Filtering

When fetching data from the server, update the loadingState to keep users informed. While the request is being processed, the loading indicator will let users know that their input has been recognised and that something is happening.

<Combobox loadingState="loading" />

NOTE: When fetching from the server based on user input you should always implement a constraint technique, like debounce or throttle, to limit the amount of requests.

Edit in Playroom

// DOCS ONLY — DO NOT COPY
const simulateFetch = (ms) => new Promise((r) => setTimeout(r, ms));
const exampleItemsFromTheServer = React.useMemo(() => [
  { label: 'Banana', value: 'banana' },
  { label: 'Blueberry', value: 'blueberry' },
  { label: 'Bubble Gum', value: 'bubble-gum' },
  { label: 'Chocolate', value: 'chocolate' },
  { label: 'Coconut', value: 'coconut' },
  { label: 'Coffee', value: 'coffee' },
  { label: 'Cookie Dough', value: 'cookie-dough' },
  { label: 'Cotton Candy', value: 'cotton-candy' },
  { label: 'Mango', value: 'mango' },
  { label: 'Matcha', value: 'matcha' },
  { label: 'Mint', value: 'mint' },
  { label: 'Oreo', value: 'oreo' },
  { label: 'Peanut Butter', value: 'peanut-butter' },
  { label: 'Pistachio', value: 'pistachio' },
  { label: 'Pumpkin', value: 'pumpkin' },
  { label: 'Salted Caramel', value: 'salted-caramel' },
  { label: 'Strawberry', value: 'strawberry' },
  { label: 'Vanilla', value: 'vanilla' },
]);
// END DOCS ONLY
// NOTE: if you display an initial list, it should be weighted towards options
// that the user is most likely to select
const initialList = React.useMemo(
  () => [
    { label: 'Chocolate', value: 'chocolate' },
    { label: 'Vanilla', value: 'vanilla' },
    { label: 'Strawberry', value: 'strawberry' },
  ],
  []
);
// loading state needed for async implementations
const [loadingState, setLoadingState] = useState('idle');
// standard state
const [inputValue, setInputValue] = useState('');
const [items, setItems] = useState(initialList);
const [selectedItem, setSelectedItem] = useState(null);
// NOTE: this should use a constraint technique, like debounce or throttle
const onInputChange = React.useCallback((text) => {
  setInputValue(text);
});
// inelegant docs-only implementation
React.useEffect(() => {
  const fetchData = async () => {
    // no input
    if (!inputValue) {
      setItems(initialList);
      return;
    }
    // set the loading state
    setLoadingState('loading');
    // simulate fetch
    await simulateFetch(Math.random() * 1000);
    setItems(() => {
      if (inputValue) {
        return exampleItemsFromTheServer.filter(({ label }) =>
          label.toLowerCase().includes(inputValue.toLowerCase())
        );
      }
      return exampleItemsFromTheServer;
    });
    // reset the loading state after fetching
    setLoadingState('idle');
  };
  fetchData();
}, [inputValue, selectedItem]);
return (
  <Field label="Async filter example">
    <Combobox
      placeholder="Input text to filter"
      loadingState={loadingState}
      items={items}
      onInputChange={onInputChange}
      inputValue={inputValue}
      onChange={setSelectedItem}
      value={selectedItem}
    />
  </Field>
);

Pagination

Paginated data is handled in the Combobox using "infinite scrolling", a technique for loading more results as the user nears the bottom of a scroll view.

To paginate results you must provide:

mode="paginated"
canLoadMore — signal that more content is available
onLoadMore — called when the user nears the bottom of the menu (if canLoadMore)
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

// DOCS ONLY — DO NOT COPY
const simulateFetch = (ms) => new Promise((r) => setTimeout(r, ms));
const itemsPerPage = 20;
const exampleItemsFromTheServer = React.useMemo(
  () =>
    Array.from({ length: 99 }).map((_, i) => ({
      label: `Item ${i + 1}`,
      value: i,
    })),
  []
);
const onInputChange = React.useCallback(
  (text) => {
    const nextState = text ? 'error' : 'idle';
    setLoadingState(nextState);
    setInputValue(text);
  },
  [items]
);
const getMessageText = React.useCallback(() => {
  return 'Search not implemented for this example';
});
// END DOCS ONLY
// loading state needed for pagination
const [loadingState, setLoadingState] = useState('idle');
// standard state
const [inputValue, setInputValue] = useState('');
const [items, setItems] = useState(
  exampleItemsFromTheServer.slice(0, itemsPerPage)
);
const [selectedItem, setSelectedItem] = useState(null);
// track the next page's availability
const canLoadMore = items.length < exampleItemsFromTheServer.length;
// simulated fetch handler
const onLoadMore = React.useCallback(async () => {
  setLoadingState('loadingMore');
  await simulateFetch(Math.random() * 1000);
  setItems((curr) =>
    exampleItemsFromTheServer.slice(0, curr.length + itemsPerPage)
  );
  setLoadingState('idle');
});
return (
  <Field label="Async pagination example">
    <Combobox
      // paginated props
      mode="paginated"
      canLoadMore={canLoadMore}
      onLoadMore={onLoadMore}
      loadingState={loadingState}
      // standard props
      placeholder="Scroll to load more items"
      loadingState={loadingState}
      items={items}
      onInputChange={onInputChange}
      inputValue={inputValue}
      onChange={setSelectedItem}
      value={selectedItem}
      // docs only
      getMessageText={getMessageText}
    />
  </Field>
);

Advanced

The Combobox is tailored for the most common usage—where possible, simplicity and reduced API surface-area is preferred. There are however features available should you need them.

State changes

The Combobox implements Downshift under-the-hood. Both onChange and onInputChange will provide "next state" as their second argument. This state is a result of the respective events, and can be used to alter the behaviour of your component.

type ComboboxState = Partial<{
  highlightedIndex: number;
  inputValue: string;
  isOpen: boolean;
  selectedItem: Item | null;
}>;

In the example below we're checking whether the input value exactly matches the recently selected item. If this is the case, we reset the list of items so they're visible next time the menu is opened.

Edit in Playroom

const itemData = React.useMemo(
  () => [
    { label: 'Chocolate', value: 'chocolate' },
    { label: 'Vanilla', value: 'vanilla' },
    { label: 'Strawberry', value: 'strawberry' },
  ],
  []
);
const [items, setItems] = useState(itemData);
const [selectedItem, setSelectedItem] = useState(null);
const [inputValue, setInputValue] = useState('');
const onInputChange = React.useCallback(
  //
  (text, state) => {
    setInputValue(text);
    setItems(() => {
      // Reset the list after selection
      if (state.selectedItem?.label === text) {
        return itemData;
      }
      // Filter the results by user input
      if (text) {
        return itemData.filter(({ label }) =>
          label.toLowerCase().includes(text.toLowerCase())
        );
      }
      // Default list when no input
      return itemData;
    });
  },
  [itemData]
);
return (
  <Field label="State changes example">
    <Combobox
      placeholder="Select an item"
      items={items}
      onInputChange={onInputChange}
      inputValue={inputValue}
      onChange={setSelectedItem}
      value={selectedItem}
    />
  </Field>
);

State reducer

For granular control of the state changing process, you can provide your own reducer. When stateReducer is called it will receive the previous state and the actionAndChanges object. actionAndChanges contains the change type, which explains why the state is being changed. It also contains the changes proposed that should occur as a consequence of that change type.

NOTE: The stateReducer should be a pure function (no side-effects), it should be declared it outside of your component.

The TS types you'll need are re-exported from this package as UseCombobox*. While Balance prefers string literals, Downshift implements an Enum for the change "type", which is exposed as stateChangeTypesEnum.

In the example below we'll uppercase the input value, and return the new value along with the rest of the changes. For all other state change types, we return the default changes.

Edit in Playroom

const itemData = React.useMemo(
  () => [
    { label: 'Chocolate', value: 'chocolate' },
    { label: 'Vanilla', value: 'vanilla' },
    { label: 'Strawberry', value: 'strawberry' },
  ],
  []
);
const [items, setItems] = useState(itemData);
const [selectedItem, setSelectedItem] = useState(null);
const [inputValue, setInputValue] = useState('');
const onInputChange = React.useCallback(
  //
  (text, allChanges) => {
    setInputValue(text);
    setItems(() => {
      // Reset the list after selection
      if (allChanges.selectedItem?.label === text) {
        return itemData;
      }
      // Filter the results by user input
      if (text) {
        return itemData.filter(({ label }) =>
          label.toLowerCase().includes(text.toLowerCase())
        );
      }
      // Default list when no input
      return itemData;
    });
  },
  [itemData]
);
const stateReducer = React.useCallback((state, actionAndChanges) => {
  const { type, changes } = actionAndChanges;
  // returning an uppercased version of the item string.
  switch (type) {
    case stateChangeTypesEnum.InputChange:
      return {
        // return normal changes.
        ...changes,
        // but taking the change from default reducer and uppercasing it.
        inputValue: changes.inputValue.toUpperCase(),
      };
    // also on selection.
    case stateChangeTypesEnum.ItemClick:
    case stateChangeTypesEnum.InputKeyDownEnter:
    case stateChangeTypesEnum.InputBlur:
      return {
        ...changes,
        // if we had an item selected.
        ...(changes.selectedItem && {
          // we will show it uppercased.
          inputValue: changes.inputValue.toUpperCase(),
        }),
      };
    default:
      return changes; // otherwise business as usual.
  }
}, []);
return (
  <Field label="State reducer example">
    <Combobox
      placeholder="Enter text or select an item to see effects"
      stateReducer={stateReducer}
      items={items}
      onInputChange={onInputChange}
      inputValue={inputValue}
      onChange={setSelectedItem}
      value={selectedItem}
    />
  </Field>
);

Messages

You can customise the message displayed to users when no items are available by providing a getMessageText callback, which has the signature:

(status: 'error' | 'noResults', inputValue: string) => string;

You can define this function outside of your component, or implement React.useCallback() to memoize it. Prefer the former where possible.

NOTE: You must account for each status in your function definition.

Edit in Playroom

const itemData = React.useMemo(
  () => [
    { label: 'Chocolate', value: 'chocolate' },
    { label: 'Vanilla', value: 'vanilla' },
    { label: 'Strawberry', value: 'strawberry' },
  ],
  []
);
// track the loading state
const [loadingState, setLoadingState] = useState('idle');
const [inputValue, setInputValue] = useState('');
const [items, setItems] = useState(itemData);
const [selectedItem, setSelectedItem] = useState(null);
// memoized callback that accounts for each status
const getMessageText = React.useCallback((status, input) => {
  switch (status) {
    case 'error':
      return 'Error fetching items, please try again.';
    case 'noMatches':
    default:
      return `No results matching "${input}".`;
  }
});
const onInputChange = React.useCallback(
  (text) => {
    setInputValue(text);
    setItems(() => {
      if (text) {
        return itemData.filter(({ label }) =>
          label.toLowerCase().includes(text.toLowerCase())
        );
      }
      return itemData;
    });
  },
  [itemData]
);
return (
  <Stack gap="large">
    <Fieldset legend="Loading state">
      <RadioGroup value={loadingState} onChange={setLoadingState}>
        <Inline gap="small">
          <Radio value="idle">Idle</Radio>
          <Radio value="error">Error</Radio>
        </Inline>
      </RadioGroup>
    </Fieldset>
    <Field label="Custom messages">
      <Combobox
        // message stuff
        getMessageText={getMessageText}
        loadingState={loadingState}
        placeholder="Custom messages"
        // business as usual
        inputValue={inputValue}
        items={items}
        onChange={setSelectedItem}
        onInputChange={onInputChange}
        value={selectedItem}
      />
    </Field>
  </Stack>
);

The environment prop

This prop is only useful if you're rendering the combobox within a different window context from where your JavaScript is running; for example, an iframe or a shadow-root.

Simply pass the window object to the environment.

<Combobox {...otherProps} environment={window} />

Combobox

Usage

Basic

Clear

Data shape

Appearance

Disabled

Invalid

Size

Placeholder

Custom item

Item height

Menu width

Async

Filtering

Pagination

Advanced

State changes

State reducer

Messages

The environment prop