Combobox

Input field that combines a text input and a list of suggested values that appear when the user enters text into the text input.

styleKeys: popoverstyleKeys: listbox

⚠️ Some props/prop values deprecated in SWAN v3.3
Refer to the information on props/prop values provided further down this page. Find more information and migration documentation in the Deprecation roadmap.

UsageGuidelinesAPI

Combobox is only available in the React API for SWAN.

Use Combobox...

To enable users to either pick a predefined value from a list or input their own.
As our default Search Input with options.
When you have a list of 15 or more options that you want to be searchable.

Don't use Combobox...

When you want to restrict input exclusively to a limited list of less than 15 options. Use a Dropdown or a Listbox instead.

Basic Combobox

A BasicCombobox is a simple-to-use convenience component that handles most typical use cases of a Combobox.

It takes a set of ComboboxOption components as children:

Each ComboboxOption must have a unique key prop holding that option's value.
The child contents of the ComboboxOption will be displayed in the popover of suggestions once the user starts typing.
Any ComboboxOption that contains more than basic text (such as a Callout, thumbnail, or custom JSX) must have a textValue prop. This is required for Accessibility
Any ComboboxOption that contains more than basic text (such as a Callout, thumbnail, or custom JSX) must have a textValue prop. This is required for accessibility and is also the value that is displayed in the text input on selection..

Any ComboboxOption that contain more than basic text (such as a Callout, thumbnail, or custom JSX) must have a textValue prop. This is required for accessibility and is also the value that is displayed in the text input on selection.

<BasicCombobox aria-labelledby="basic-combobox" placeholder="Text...">
  <ComboboxOption key="some fruit">🥝</ComboboxOption>
  <ComboboxOption key="red panda">Red Panda</ComboboxOption>
  <ComboboxOption key="cat">Cat</ComboboxOption>
  <ComboboxOption key="dog">Dog</ComboboxOption>
  <ComboboxOption key="aardvark">Aardvark</ComboboxOption>
  <ComboboxOption key="kangaroo">Kangaroo</ComboboxOption>
  <ComboboxOption key="snake">Snake</ComboboxOption>
  <ComboboxOption key="catfish">Catfish</ComboboxOption>
</BasicCombobox>

<BasicCombobox aria-labelledby="basic-combobox" placeholder="Text...">
  <ComboboxOption key="some fruit">🥝</ComboboxOption>
  <ComboboxOption key="red panda">Red Panda</ComboboxOption>
  <ComboboxOption key="cat">Cat</ComboboxOption>
  <ComboboxOption key="dog">Dog</ComboboxOption>
  <ComboboxOption key="aardvark">Aardvark</ComboboxOption>
  <ComboboxOption key="kangaroo">Kangaroo</ComboboxOption>
  <ComboboxOption key="snake">Snake</ComboboxOption>
  <ComboboxOption key="catfish">Catfish</ComboboxOption>
</BasicCombobox>

Full Combobox

A Full Combobox allows you to put additional content inside the ComboboxPopover sub-component, notably a ComboboxPopoverTitle above the ComboboxList.

<Combobox aria-label="Favorite Animal">
  <ComboboxInput placeholder="Enter text..." />
  <ComboboxPopover>
    <ComboboxPopoverTitle>Popular choices:</ComboboxPopoverTitle>
    <ComboboxList>
      <ComboboxOption key="red panda">Red Panda</ComboboxOption>
      <ComboboxOption key="cat">Cat</ComboboxOption>
      <ComboboxOption key="dog">Dog</ComboboxOption>
      <ComboboxOption key="aardvark">Aardvark</ComboboxOption>
      <ComboboxOption key="kangaroo">Kangaroo</ComboboxOption>
      <ComboboxOption key="snake">Snake</ComboboxOption>
      <ComboboxOption key="catfish">Catfish</ComboboxOption>
    </ComboboxList>
  </ComboboxPopover>
</Combobox>

<Combobox aria-label="Favorite Animal">
  <ComboboxInput placeholder="Enter text..." />
  <ComboboxPopover>
    <ComboboxPopoverTitle>Popular choices:</ComboboxPopoverTitle>
    <ComboboxList>
      <ComboboxOption key="red panda">Red Panda</ComboboxOption>
      <ComboboxOption key="cat">Cat</ComboboxOption>
      <ComboboxOption key="dog">Dog</ComboboxOption>
      <ComboboxOption key="aardvark">Aardvark</ComboboxOption>
      <ComboboxOption key="kangaroo">Kangaroo</ComboboxOption>
      <ComboboxOption key="snake">Snake</ComboboxOption>
      <ComboboxOption key="catfish">Catfish</ComboboxOption>
    </ComboboxList>
  </ComboboxPopover>
</Combobox>

With thumbnail container

Use ComboboxOptionThumbnailContainer, which contains a square FluidImage, to display square thumbnail images in selections.

<Combobox aria-label="Favorite Animal">
  <ComboboxInput placeholder="Enter text..." />
  <ComboboxPopover>
    <ComboboxPopoverTitle>Popular fruits:</ComboboxPopoverTitle>
    <ComboboxList>
      <ComboboxOption
        key="apple"
        textValue="An apple a day keeps doctor away"
        withThumbnail
      >
        <ComboboxOptionThumbnailContainer>
          <FluidImage
            src="https://picsum.photos/100/100?cb=1"
            alt="my thumbnail"
          />
        </ComboboxOptionThumbnailContainer>
        <ComboboxOptionTextContainer>
          An apple a day keeps doctor away
          <Typography fontSize={'-2'} textColor="grey-700">
            Apple
          </Typography>
        </ComboboxOptionTextContainer>
      </ComboboxOption>
      <ComboboxOption
        key="mango"
        textValue="lorem ipsum mango taste delicious and this text is going to very long, I mean very very very long. lorem ipsum some text having no meaning but just placeholder and blah blah blah blah blah."
        withThumbnail
      >
        <ComboboxOptionThumbnailContainer>
          <FluidImage
            src="https://picsum.photos/100/100?cb=2"
            alt="my thumbnail"
          />
        </ComboboxOptionThumbnailContainer>
        <ComboboxOptionTextContainer>
          Mango the king of fruits and this text is going to very long, I mean
          very very very long. lorem ipsum some text having no meaning but just
          placeholder and blah blah blah blah blah. This should be ideally
          wrapped to the next line
          <Typography fontSize={'-2'} textColor="grey-700">
            Mango
          </Typography>
        </ComboboxOptionTextContainer>
      </ComboboxOption>
    </ComboboxList>
  </ComboboxPopover>
</Combobox>

<Combobox aria-label="Favorite Animal">
  <ComboboxInput placeholder="Enter text..." />
  <ComboboxPopover>
    <ComboboxPopoverTitle>Popular fruits:</ComboboxPopoverTitle>
    <ComboboxList>
      <ComboboxOption
        key="apple"
        textValue="An apple a day keeps doctor away"
        withThumbnail
      >
        <ComboboxOptionThumbnailContainer>
          <FluidImage
            src="https://picsum.photos/100/100?cb=1"
            alt="my thumbnail"
          />
        </ComboboxOptionThumbnailContainer>
        <ComboboxOptionTextContainer>
          An apple a day keeps doctor away
          <Typography fontSize={'-2'} textColor="grey-700">
            Apple
          </Typography>
        </ComboboxOptionTextContainer>
      </ComboboxOption>
      <ComboboxOption
        key="mango"
        textValue="lorem ipsum mango taste delicious and this text is going to very long, I mean very very very long. lorem ipsum some text having no meaning but just placeholder and blah blah blah blah blah."
        withThumbnail
      >
        <ComboboxOptionThumbnailContainer>
          <FluidImage
            src="https://picsum.photos/100/100?cb=2"
            alt="my thumbnail"
          />
        </ComboboxOptionThumbnailContainer>
        <ComboboxOptionTextContainer>
          Mango the king of fruits and this text is going to very long, I mean
          very very very long. lorem ipsum some text having no meaning but just
          placeholder and blah blah blah blah blah. This should be ideally
          wrapped to the next line
          <Typography fontSize={'-2'} textColor="grey-700">
            Mango
          </Typography>
        </ComboboxOptionTextContainer>
      </ComboboxOption>
    </ComboboxList>
  </ComboboxPopover>
</Combobox>

With floating label

Use ComboboxWithFloatingLabel to move the label inside the input above the selection. This creates visual harmony with other form elements like text inputs that support floating labels. Keep label text short or use the fullWidth prop to maximize width.

ReactVanilla

<ComboboxWithFloatingLabel>
  <ComboboxInput />
  <ComboboxFloatingLabel>Mascot</ComboboxFloatingLabel>
  <ComboboxPopover>
    <ComboboxPopoverTitle>Popular choices:</ComboboxPopoverTitle>
    <ComboboxList>
      <ComboboxOption key="swan">Swan</ComboboxOption>
      <ComboboxOption key="cat">Cat</ComboboxOption>
      <ComboboxOption key="dog">Dog</ComboboxOption>
    </ComboboxList>
  </ComboboxPopover>
</ComboboxWithFloatingLabel>

<ComboboxWithFloatingLabel>
  <ComboboxInput />
  <ComboboxFloatingLabel>Mascot</ComboboxFloatingLabel>
  <ComboboxPopover>
    <ComboboxPopoverTitle>Popular choices:</ComboboxPopoverTitle>
    <ComboboxList>
      <ComboboxOption key="swan">Swan</ComboboxOption>
      <ComboboxOption key="cat">Cat</ComboboxOption>
      <ComboboxOption key="dog">Dog</ComboboxOption>
    </ComboboxList>
  </ComboboxPopover>
</ComboboxWithFloatingLabel>

<div class="swan-input-with-floating-label">
  <input
    type="text"
    placeholder=" "
    class="swan-polyfill-empty swan-input"
    value=""
  /><label>Floating label</label>
</div>

<div class="swan-input-with-floating-label">
  <input
    type="text"
    placeholder=" "
    class="swan-polyfill-empty swan-input"
    value=""
  /><label>Floating label</label>
</div>

With Search Input

Use ComboboxWithSearchInput to transform a Combobox in our default search field.

Refer to Search Input guidelines

<Combobox aria-label="Clothing & Bags">
  <ComboboxSearchInput
    placeholder="Search for Clothing & Bags"
    accessibleTextForSearchButton="Search for a shirt or a bag"
    accessibleTextForClearButton="Clear results. Then search again for a shirt or a bag. Or tab to next page area"
  />
  <ComboboxPopover>
    <ComboboxList>
      <ComboboxOption key="t-shirts">T-shirts</ComboboxOption>
      <ComboboxOption key="polo shirts">Polo shirts</ComboboxOption>
      <ComboboxOption key="dress shirts">Dress shirts</ComboboxOption>
      <ComboboxOption key="sweatshirts">Sweatshirts</ComboboxOption>
      <ComboboxOption key="jackets">Jackets</ComboboxOption>
      <ComboboxOption key="backpack">Backpack</ComboboxOption>
      <ComboboxOption key="cooler bags">Cooler Bags</ComboboxOption>
    </ComboboxList>
  </ComboboxPopover>
</Combobox>

<Combobox aria-label="Clothing & Bags">
  <ComboboxSearchInput
    placeholder="Search for Clothing & Bags"
    accessibleTextForSearchButton="Search for a shirt or a bag"
    accessibleTextForClearButton="Clear results. Then search again for a shirt or a bag. Or tab to next page area"
  />
  <ComboboxPopover>
    <ComboboxList>
      <ComboboxOption key="t-shirts">T-shirts</ComboboxOption>
      <ComboboxOption key="polo shirts">Polo shirts</ComboboxOption>
      <ComboboxOption key="dress shirts">Dress shirts</ComboboxOption>
      <ComboboxOption key="sweatshirts">Sweatshirts</ComboboxOption>
      <ComboboxOption key="jackets">Jackets</ComboboxOption>
      <ComboboxOption key="backpack">Backpack</ComboboxOption>
      <ComboboxOption key="cooler bags">Cooler Bags</ComboboxOption>
    </ComboboxList>
  </ComboboxPopover>
</Combobox>

Allow custom value

Use allowsCustomValue when you want to allow users to enter custom text in a Combobox, even if the entered text does not match any of the predefined options.

This will not change when or how onSelectionChange is called when an option is selected.

<BasicCombobox
  aria-label="Allow custom value"
  allowsCustomValue
  placeholder="custom value allowed"
>
  <ComboboxOption key="some fruit">🥝</ComboboxOption>
  <ComboboxOption key="red panda">Red Panda</ComboboxOption>
  <ComboboxOption key="cat">Cat</ComboboxOption>
  <ComboboxOption key="dog">Dog</ComboboxOption>
  <ComboboxOption key="aardvark">Aardvark</ComboboxOption>
  <ComboboxOption key="kangaroo">Kangaroo</ComboboxOption>
  <ComboboxOption key="snake">Snake</ComboboxOption>
  <ComboboxOption key="catfish">Catfish</ComboboxOption>
</BasicCombobox>

<BasicCombobox
  aria-label="Allow custom value"
  allowsCustomValue
  placeholder="custom value allowed"
>
  <ComboboxOption key="some fruit">🥝</ComboboxOption>
  <ComboboxOption key="red panda">Red Panda</ComboboxOption>
  <ComboboxOption key="cat">Cat</ComboboxOption>
  <ComboboxOption key="dog">Dog</ComboboxOption>
  <ComboboxOption key="aardvark">Aardvark</ComboboxOption>
  <ComboboxOption key="kangaroo">Kangaroo</ComboboxOption>
  <ComboboxOption key="snake">Snake</ComboboxOption>
  <ComboboxOption key="catfish">Catfish</ComboboxOption>
</BasicCombobox>

Managing state

Add the disableAutoFilter prop to the Combobox when you also want to control the list of filtered options.

For better performance with large or dynamic data, use the dynamic collections API by passing an array into the items prop of the Combobox and a render function as the child of ComboboxList.

() => {
  const options = [
    { key: 'red panda', text: 'Red Panda' },
    { key: 'cat', text: 'Cat' },
    { key: 'dog', text: 'Dog' },
    { key: 'aardvark', text: 'Aardvark' },
    { key: 'kangaroo', text: 'Kangaroo' },
    { key: 'snake', text: 'Snake' },
    { key: 'catfish', text: 'Catfish' },
  ]

  const [fieldState, setFieldState] = React.useState({
    selectedKey: '',
    inputValue: '',
  })

  const onSelectionChange = React.useCallback(key => {
    const selectedItem = options.find(option => option.key === key)
    setFieldState({
      inputValue: selectedItem && selectedItem.text ? selectedItem.text : '',
      selectedKey: key ? key.toString() : '',
    })
  }, [])

  const onInputChange = React.useCallback(value => {
    setFieldState(prevState => ({
      inputValue: value,
      selectedKey: value === '' ? null : prevState.selectedKey,
    }))
  }, [])

  const filteredOptions = React.useMemo(
    () =>
      options.filter(o =>
        o.key.startsWith(fieldState.inputValue.toLocaleLowerCase()),
      ),
    [fieldState.inputValue],
  )

  return (
    <StandardForm>
      <FormField>
        <FormLabel>Controlled Selected Value + Input Text</FormLabel>
        <FormInputGroup>
          <Combobox
            selectedKey={fieldState.selectedKey || undefined}
            onSelectionChange={onSelectionChange}
            aria-label="Favorite Animal"
            onInputChange={val => onInputChange(val || '')}
            inputValue={fieldState.inputValue}
          >
            <ComboboxInput placeholder="Favorite Animal..." />
            <ComboboxPopover>
              <ComboboxList>
                {options.map(o => (
                  <ComboboxOption key={o.key}>{o.text}</ComboboxOption>
                ))}
              </ComboboxList>
            </ComboboxPopover>
          </Combobox>
        </FormInputGroup>
      </FormField>
      <FormField>
        <FormLabel>Fully Controlled + Filtering</FormLabel>
        <FormInputGroup>
          <Combobox
            selectedKey={fieldState.selectedKey || undefined}
            onSelectionChange={onSelectionChange}
            disableAutoFilter
            aria-label="Favorite Animal"
            onInputChange={val => onInputChange(val)}
            inputValue={fieldState.inputValue}
            items={filteredOptions}
          >
            <ComboboxInput placeholder="Favorite Animal..." />
            <ComboboxPopover>
              <ComboboxList>
                {o => <ComboboxOption key={o.key}>{o.text}</ComboboxOption>}
              </ComboboxList>
            </ComboboxPopover>
          </Combobox>
        </FormInputGroup>
      </FormField>
    </StandardForm>
  )
}

() => {
  const options = [
    { key: 'red panda', text: 'Red Panda' },
    { key: 'cat', text: 'Cat' },
    { key: 'dog', text: 'Dog' },
    { key: 'aardvark', text: 'Aardvark' },
    { key: 'kangaroo', text: 'Kangaroo' },
    { key: 'snake', text: 'Snake' },
    { key: 'catfish', text: 'Catfish' },
  ]

  const [fieldState, setFieldState] = React.useState({
    selectedKey: '',
    inputValue: '',
  })

  const onSelectionChange = React.useCallback(key => {
    const selectedItem = options.find(option => option.key === key)
    setFieldState({
      inputValue: selectedItem && selectedItem.text ? selectedItem.text : '',
      selectedKey: key ? key.toString() : '',
    })
  }, [])

  const onInputChange = React.useCallback(value => {
    setFieldState(prevState => ({
      inputValue: value,
      selectedKey: value === '' ? null : prevState.selectedKey,
    }))
  }, [])

  const filteredOptions = React.useMemo(
    () =>
      options.filter(o =>
        o.key.startsWith(fieldState.inputValue.toLocaleLowerCase()),
      ),
    [fieldState.inputValue],
  )

  return (
    <StandardForm>
      <FormField>
        <FormLabel>Controlled Selected Value + Input Text</FormLabel>
        <FormInputGroup>
          <Combobox
            selectedKey={fieldState.selectedKey || undefined}
            onSelectionChange={onSelectionChange}
            aria-label="Favorite Animal"
            onInputChange={val => onInputChange(val || '')}
            inputValue={fieldState.inputValue}
          >
            <ComboboxInput placeholder="Favorite Animal..." />
            <ComboboxPopover>
              <ComboboxList>
                {options.map(o => (
                  <ComboboxOption key={o.key}>{o.text}</ComboboxOption>
                ))}
              </ComboboxList>
            </ComboboxPopover>
          </Combobox>
        </FormInputGroup>
      </FormField>
      <FormField>
        <FormLabel>Fully Controlled + Filtering</FormLabel>
        <FormInputGroup>
          <Combobox
            selectedKey={fieldState.selectedKey || undefined}
            onSelectionChange={onSelectionChange}
            disableAutoFilter
            aria-label="Favorite Animal"
            onInputChange={val => onInputChange(val)}
            inputValue={fieldState.inputValue}
            items={filteredOptions}
          >
            <ComboboxInput placeholder="Favorite Animal..." />
            <ComboboxPopover>
              <ComboboxList>
                {o => <ComboboxOption key={o.key}>{o.text}</ComboboxOption>}
              </ComboboxList>
            </ComboboxPopover>
          </Combobox>
        </FormInputGroup>
      </FormField>
    </StandardForm>
  )
}

Dynamic collections

Use the dynamic collections API for optimal performance with large or dynamic data. Pass an array into the items prop of the Combobox and a render function as the child of ComboboxList.

The useAsyncList hook can be used when dealing with async data in order to fetch remote data (this is optional). Alternatively, you can manage async data similarly as in the controlled Combobox example above. Refer to the React-Area documentation for useAsyncList.

By default, the popover will remain closed if there are no results, typically before the initial request after a keypress has resolved. To enable the popover to open and display results after the request concludes, include the allowEmptyCollection prop. Consider incorporating a loading state into the popover to prevent presenting an empty popover.

() => {
  const list = useAsyncList({
    async load({ signal, filterText }) {
      const res = await fetch(
        `https://swapi.py4e.com/api/people/?search=${filterText}`,
        { signal },
      )
      const json = await res.json()

      return {
        items: json.results,
      }
    },
  })

  return (
    <Combobox
      aria-label="Favorite Star Wars Character"
      items={list.items}
      inputValue={list.filterText}
      onInputChange={list.setFilterText}
      allowEmptyCollection
    >
      <ComboboxInput placeholder="Select an character..." />
      <ComboboxPopover>
        <ComboboxList>
          {o => <ComboboxOption key={o.url}>{o.name}</ComboboxOption>}
        </ComboboxList>
        {list.items.length === 0 && list.isLoading ? (
          <Box px={3} pb={4} pt={0}>
            <Spinner
              accessibleText="Loading..."
              size="mini"
              layout="horizontal"
              showText
            />
          </Box>
        ) : null}
      </ComboboxPopover>
    </Combobox>
  )
}

() => {
  const list = useAsyncList({
    async load({ signal, filterText }) {
      const res = await fetch(
        `https://swapi.py4e.com/api/people/?search=${filterText}`,
        { signal },
      )
      const json = await res.json()

      return {
        items: json.results,
      }
    },
  })

  return (
    <Combobox
      aria-label="Favorite Star Wars Character"
      items={list.items}
      inputValue={list.filterText}
      onInputChange={list.setFilterText}
      allowEmptyCollection
    >
      <ComboboxInput placeholder="Select an character..." />
      <ComboboxPopover>
        <ComboboxList>
          {o => <ComboboxOption key={o.url}>{o.name}</ComboboxOption>}
        </ComboboxList>
        {list.items.length === 0 && list.isLoading ? (
          <Box px={3} pb={4} pt={0}>
            <Spinner
              accessibleText="Loading..."
              size="mini"
              layout="horizontal"
              showText
            />
          </Box>
        ) : null}
      </ComboboxPopover>
    </Combobox>
  )
}

Placement

The Combobox prioritizes usability through generous padding and a large font.

Ensure the Combobox has sufficient room for rendering on the page.
Account for the possibility of translated text being longer than English text to prevent display issues.

Props

BasicCombobox

This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.