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

/** 
  This filtering example is very basic and only meant to introduce the component API.
  Please check the recipes section for a correct reference implementation.
*/
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.

Actions such as "Create new" can be shown in the footer using the footerItem prop. The footer item is just a normal item rendered differently (for accessibility reasons) so most of the behavior is left to the consumer.

Below is a sample of how to implement a "Create new" item in the footer.

Edit in Playroom

const itemData = React.useMemo(
  () => [
    { label: 'Chocolate', value: 'chocolate' },
    { label: 'Vanilla', value: 'vanilla' },
    { label: 'Strawberry', value: 'strawberry' },
    { label: 'Pineapple', value: 'pineapple' },
    { label: 'Mango', value: 'mango' },
    { label: 'Marshmallow', value: 'marshmallow' },
    { label: 'Peach', value: 'peach' },
    { label: 'Watermelon', value: 'watermelon' },
    { label: 'Guava', value: 'guava' },
    { label: 'Custard apple', value: 'custardapple' },
    { label: 'Plum', value: 'plum' },
    { label: 'Rockmelon', value: 'rockmelon' },
  ],
  []
);
// prepare internal state, which will be passed to the component
const [inputValue, setInputValue] = useState('');
const [items, setItems] = useState(itemData);
const [selectedItem, setSelectedItem] = useState(null);
const onInputChange = React.useCallback(
  (text) => {
    setInputValue(text);
    setItems(() => {
      if (text) {
        return itemData.filter(({ label }) =>
          label.toLowerCase().includes(text.toLowerCase())
        );
      }
      return itemData;
    });
  },
  [itemData]
);
const onClear = React.useCallback(() => {
  setInputValue('');
  setItems(itemData);
  setSelectedItem(null);
}, [itemData]);
const handleCreateNewClick = React.useCallback(() => {
  onClear();
  // Allow user to create a new item here (by opening a drawer or something)
}, [onClear, inputValue]);
const footerItem = React.useMemo(() => {
  // If some item is selected, footer is not needed
  if (selectedItem) {
    return null;
  }
  // If the user has entered something that matches with exact item value, footer is not needed
  const exactMatchFound = itemData.find(
    (item) => item && item.value.toLowerCase() === inputValue.toLowerCase()
  );
  if (exactMatchFound) {
    return null;
  }
  // Return actual footer item
  return {
    label: '_createNew',
    value: 'Create new',
  };
}, [inputValue, itemData, selectedItem]);
const footerNode = React.useMemo(() => {
  if (!inputValue) {
    return <TextLinkButton>Create new item</TextLinkButton>;
  }
  return (
    <Flex justifyContent="space-between" paddingRight="large" flexGrow={1}>
      <Text>{`"${inputValue}"`} &nbsp; </Text>
      <TextLinkButton>Create new</TextLinkButton>
    </Flex>
  );
}, [inputValue]);
// We must use a custom renderer when using footer items.
const itemRenderer = React.useCallback(
  (item) => {
    // We render the footer item differnetly based on a value check.
    return item.value === footerItem?.value ? footerNode : <>{item.label}</>;
  },
  [footerItem, footerNode]
);
return (
  <Field label="Footer example">
    <Combobox
      placeholder="Select an item"
      inputValue={inputValue}
      items={items}
      footerItem={footerItem}
      itemRenderer={itemRenderer}
      onChange={(item) => {
        // We check if the item is a "Create new" item which is how different behaviors are applied.
        if (item?.value === footerItem?.value) {
          handleCreateNewClick();
          return;
        }
        setSelectedItem(item);
      }}
      onInputChange={onInputChange}
      value={selectedItem}
      onClear={onClear}
    />
  </Field>
);

Grouping, dividers and sticky items

We cannot have hierarchical data in a combobox, instead we can have the illusion of grouped items by inserting disabled and unselectable items into the list and rendering them differently.

Edit in Playroom

type GroupedItem = {
  label: string;
  value: string;
  groupLabel?: string;
  divider?: boolean;
};
/**
 * The grouped data can be in many different shapes, this
 *  is just one example.
 */
const groupedFlavours = React.useMemo(() => {
  return [
    {
      groupId: 'group_a',
      groupLabel: 'Group A',
      flavours: [
        {
          label: 'Almond Fudge',
          value: 'almond_fudge',
        },
        {
          label: 'Apple Pie',
          value: 'apple_pie',
        },
        {
          label: 'Avocado',
          value: 'avocado',
        },
        {
          label: 'Amaretto',
          value: 'amaretto',
        },
      ],
    },
    {
      groupId: 'group_b',
      groupLabel: 'Group B',
      flavours: [
        {
          label: 'Blueberry Cheesecake',
          value: 'blueberry_cheesecake',
        },
        {
          label: 'Butter Pecan',
          value: 'nutter_pecan',
        },
        {
          label: 'Banana Split',
          value: 'banana_split',
        },
        {
          label: 'Brownie Batter',
          value: 'brownie_batter',
        },
      ],
    },
    {
      groupId: 'group_c',
      groupLabel: 'Group C',
      flavours: [
        {
          label: 'Cookies and Cream',
          value: 'cookies_and_cream',
        },
        {
          label: 'Chocolate Chip Cookie Dough',
          value: 'chocolate_chip_cookie_dough',
        },
        {
          label: 'Cherry Garcia',
          value: 'cherry_garcia',
        },
        {
          label: 'Caramel Swirl',
          value: 'caramel_swirl',
        },
      ],
    },
    {
      groupId: 'group_d',
      groupLabel: 'Group D',
      flavours: [
        {
          label: 'Dulce de Leche',
          value: 'dulce_de_leche',
        },
        {
          label: 'Double Chocolate',
          value: 'double_chocolate',
        },
        {
          label: 'Dragon Fruit',
          value: 'dragon_fruit',
        },
        {
          label: 'Dark Chocolate Raspberry',
          value: 'dark_chocolate_raspberry',
        },
      ],
    },
  ];
}, []);
const [inputValue, setInputValue] = useState('');
/**
 * Make sure to apply filtering to your grouped data, not the flat data
 *  or you'll end up with empty groups.
 **/
const filteredGroupedFlavours = React.useMemo(() => {
  if (!inputValue.length) {
    return groupedFlavours;
  }
  return groupedFlavours
    .map((flavourGroup) => {
      return {
        ...flavourGroup,
        flavours: flavourGroup.flavours.filter((flavour) => {
          return flavour.label.toLowerCase().includes(inputValue.toLowerCase());
        }),
      };
    })
    .filter((flavourGroup) => {
      return flavourGroup.flavours.length;
    });
}, [groupedFlavours, inputValue]);
/**
 * We need to flatten the grouped data into a
 *  single list with some metadata. This might change
 *  depending on your data structure and requirements.
 */
const itemData = React.useMemo(() => {
  const items: Array<GroupedItem> = [];
  filteredGroupedFlavours.forEach((flavourGroup, flavourGroupIdx) => {
    if (flavourGroup.flavours.length === 0) {
      return;
    }
    items.push({
      label: `${flavourGroup.groupLabel}_header`,
      value: `${flavourGroup.groupLabel}_header`,
      groupLabel: flavourGroup.groupLabel,
    });
    flavourGroup.flavours.forEach((flavour) => {
      items.push({
        label: flavour.label,
        value: flavour.value,
      });
    });
    if (
      flavourGroup.flavours.length &&
      flavourGroupIdx < filteredGroupedFlavours.length - 1
    ) {
      items.push({
        label: `${flavourGroup.groupLabel}_footer`,
        value: `${flavourGroup.groupLabel}_footer`,
        divider: true,
      });
    }
  });
  return items;
}, [filteredGroupedFlavours]);
/**
 * This is not necessary to have groups and dividers but sticky
 *  group labels are nice.
 **/
const stickyIndexes = React.useMemo(() => {
  const indices: number[] = [];
  itemData.forEach((item, index) => {
    if (item.groupLabel?.length) {
      indices.push(index);
    }
  });
  return indices;
}, [itemData]);
const [items, setItems] = useState(itemData);
const [selectedItem, setSelectedItem] = useState<GroupedItem | null>();
const onInputChange = React.useCallback((text) => {
  setInputValue(text);
}, []);
const onClear = React.useCallback(() => {
  setInputValue('');
  setItems(itemData);
  setSelectedItem(null);
}, [itemData]);
React.useEffect(() => {
  setItems(itemData);
}, [itemData]);
return (
  <Field label="Group & dividers">
    <Combobox
      footerItemHeight={30}
      inputValue={inputValue}
      itemHeight={(i) => {
        const item = items[i];
        if (item.groupLabel?.length) {
          return 40;
        }
        if (item.divider) {
          return 1;
        }
        return 50;
      }}
      itemRenderer={(item) => {
        if (item.groupLabel?.length) {
          return (
            <Box paddingLeft="small">
              <Text color="dim" size="xsmall" weight="bold">
                {item.groupLabel}
              </Text>
            </Box>
          );
        }
        if (item.divider) {
          return <Divider />;
        }
        return <Text>{item.label}</Text>;
      }}
      items={items}
      // We must disable the group items so user can't select them
      itemToDisabled={(item) => {
        const isGroupItem = !!(item.groupLabel?.length || item.divider);
        return isGroupItem;
      }}
      // We must make the group items not selectable so we have full control over the layout.
      itemToSelectable={(item) => {
        const isGroupItem = !!(item.groupLabel?.length || item.divider);
        return !isGroupItem;
      }}
      placeholder="Select an item"
      stickyIndexes={stickyIndexes}
      value={selectedItem}
      onChange={setSelectedItem}
      onClear={onClear}
      onInputChange={onInputChange}
    />
  </Field>
);

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} />

Recipes

Reference implementations for comboboxes of varying complexity.

Client side filtering with dynamic item height and quick add

Edit in Playroom

type ItemType = {
  label: string;
  value: string;
  description?: string;
  disabled?: boolean;
};
// This would usually be fetched above this component and passed in as a prop
const serverItemList = React.useMemo((): Array<ItemType> => {
  return [
    { label: 'Chocolate', value: 'chocolate' },
    { label: 'Vanilla', value: 'vanilla' },
    { label: 'Strawberry', value: 'strawberry' },
    {
      label: 'Pineapple',
      value: 'pineapple',
      description:
        'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.',
    },
    { label: 'Mango', value: 'mango' },
    { label: 'Marshmallow', value: 'marshmallow' },
    { label: 'Peach', value: 'peach' },
    {
      label: 'Watermelon',
      value: 'watermelon',
      description:
        'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.',
    },
    { label: 'Guava', value: 'guava' },
    {
      label: 'Custard apple',
      value: 'custardapple',
      description:
        'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.',
    },
    { label: 'Plum', value: 'plum' },
    { label: 'Rockmelon', value: 'rockmelon' },
  ];
}, []);
const createNewItem: ItemType = React.useMemo(() => {
  return {
    label: 'Create new',
    value: '_createNew',
  };
}, []);
const emptyStateItem: ItemType = React.useMemo(() => {
  return {
    label: '',
    value: '_emptyState',
  };
}, []);
// Perform any in-app filtering and sorting
const filteredServerItemList = React.useMemo(() => {
  return serverItemList
    .filter(() => {
      return true;
    })
    .sort((a, b) => {
      return a.label.localeCompare(b.label);
    });
}, [serverItemList]);
const [searchInputValue, setSearchInputValue] = useState('');
const [selectedItem, setSelectedItem] = useState<ItemType | null>(null);
const searchedItemList = React.useMemo(() => {
  // Perform all search on trimmed and lower case
  const formattedSearchValue = searchInputValue?.toLowerCase().trim();
  // Return all items if user input is empty
  if (!formattedSearchValue?.length) {
    return filteredServerItemList;
  }
  // Return all items if search value is the same as selected item i.e user is not searching
  const exactSelectedItemMatched =
    !!selectedItem &&
    formattedSearchValue === selectedItem.label.toLowerCase().trim();
  if (exactSelectedItemMatched) {
    return filteredServerItemList;
  }
  const filteredItems = filteredServerItemList.filter((item) => {
    return item.label.toLowerCase().trim().includes(formattedSearchValue);
  });
  if (filteredItems?.length) {
    return filteredItems;
  }
  // Return a special item when there are no items
  return [
    {
      // Different messages based on whether the list is empty or no matches from user search
      label: !filteredServerItemList.length
        ? `There are no items in this list, click "Create new" below to get started.`
        : `There are no items in this list matching your search criteria.`,
      value: emptyStateItem.value,
      disabled: true,
    },
  ];
}, [filteredServerItemList, searchInputValue, selectedItem]);
const onInputChange = React.useCallback(
  (text) => {
    setSearchInputValue(text);
  },
  [filteredServerItemList]
);
const onClear = React.useCallback(() => {
  setSearchInputValue('');
  setSelectedItem(null);
}, [filteredServerItemList]);
const handleCreateNewClick = React.useCallback(() => {
  onClear();
  // Allow user to create a new item here (by opening a drawer or something)
}, [onClear]);
const footerNode = React.useMemo(() => {
  const formattedInputValue = searchInputValue?.toLowerCase().trim();
  if (!formattedInputValue.length) {
    return <TextLinkButton>Create new</TextLinkButton>;
  }
  const exactSelectedItemMatched = filteredServerItemList.find((item) => {
    return item.label.toLowerCase().trim() === formattedInputValue;
  });
  return (
    <Flex flexGrow={1} justifyContent="space-between" paddingRight="large">
      {exactSelectedItemMatched ? null : (
        <Text>{`"${searchInputValue}"`} &nbsp; </Text>
      )}
      <Text>
        <TextLinkButton>Create new</TextLinkButton>
      </Text>
    </Flex>
  );
}, [searchInputValue, selectedItem]);
const itemRenderer = React.useCallback(
  (item: ItemType) => {
    if (item.value === emptyStateItem.value) {
      return (
        <Box paddingY="medium">
          <Text align="center" color="dim">
            {item.label}
          </Text>
        </Box>
      );
    }
    if (createNewItem.value === item.value) {
      return footerNode;
    }
    return (
      <Stack gap="small">
        <Text weight="semibold">{item.label}</Text>
        {item.description?.length ? (
          <Text size="small" color="muted">
            {item.description}
          </Text>
        ) : null}
      </Stack>
    );
  },
  [createNewItem, footerNode]
);
const minItemHeight = 56;
const menuWidth = 400;
return (
  <div style={{ width: menuWidth }}>
    <Field label="Flavours">
      <Combobox
        footerItem={createNewItem}
        footerItemHeight={minItemHeight}
        inputValue={searchInputValue}
        itemRenderer={itemRenderer}
        items={searchedItemList}
        itemHeight={(i) => {
          const item = searchedItemList[i];
          if (item.value === emptyStateItem.value) {
            return minItemHeight + 10;
          }
          if (!item.description?.length) {
            return minItemHeight;
          }
          // This can be skipped if your items are all roughly the same size.
          return (
            comoboboxDynamicTextContainerItemHeight({
              lineHeight: 21,
              minContainerWidth: 30,
              maxCharactersPerMinContainerWidth: 4,
              characterCount:
                item.value.length + (item.description?.length || 0),
              containerWidth: menuWidth - 10,
            }) + minItemHeight
          );
        }}
        menuWidth={menuWidth}
        placeholder="Select a flavour"
        value={selectedItem}
        onChange={(item) => {
          if (item?.value === createNewItem?.value) {
            handleCreateNewClick();
            return;
          }
          setSelectedItem(item);
        }}
        onClear={onClear}
        onInputChange={onInputChange}
      />
    </Field>
  </div>
);

Combobox

Alternatives

Usage

Basic

Clear

Data shape

Appearance

Disabled

Invalid

Size

Placeholder

Custom item

Item height

Menu width

Async

Filtering

Advanced

Footer action

Grouping, dividers and sticky items

State changes

State reducer

Messages

The environment prop

Recipes

Client side filtering with dynamic item height and quick add