Autocomplete

Autocomplete allows users to quickly filter through a list of options and pick one or more values for a field.

Page navigation navigation

React

readyNot reviewed for a11y

Storybook|Source

Rails

readyNot reviewed for a11y

Docs|Lookbook|Source

Figma

View in Figma|

React examples

Default

Label

<FormControl>
  <FormControl.Label id="autocompleteLabel-default">Label</FormControl.Label>
  <Autocomplete>
    <Autocomplete.Input />
    <Autocomplete.Overlay>
      <Autocomplete.Menu
        selectedItemIds={[]}
        aria-labelledby="autocompleteLabel-default"
        items={[
          {text: 'Components', id: '0'},
          {text: 'Figma', id: '1'},
          {text: 'Design patterns', id: '2'},
          {text: 'Design tokens', id: '3'},
          {text: 'Icons', id: '4'},
          {text: 'Rails', id: '5'},
          {text: 'React', id: '6'},
        ]}
      />
    </Autocomplete.Overlay>
  </Autocomplete>
</FormControl>

<FormControl>
  <FormControl.Label id="autocompleteLabel-default">Label</FormControl.Label>
  <Autocomplete>
    <Autocomplete.Input />
    <Autocomplete.Overlay>
      <Autocomplete.Menu
        selectedItemIds={[]}
        aria-labelledby="autocompleteLabel-default"
        items={[
          {text: 'Components', id: '0'},
          {text: 'Figma', id: '1'},
          {text: 'Design patterns', id: '2'},
          {text: 'Design tokens', id: '3'},
          {text: 'Icons', id: '4'},
          {text: 'Rails', id: '5'},
          {text: 'React', id: '6'},
        ]}
      />
    </Autocomplete.Overlay>
  </Autocomplete>
</FormControl>

Multi-select

Label

import React from 'react'
import {Autocomplete, FormControl} from '@primer/react'


export default function Multiselect() {
  const [selectedItemIds, setSelectedItemIds] = React.useState<Array<string>>([])


  return (
    <>
      <FormControl>
        <FormControl.Label id="autocompleteLabel-multiselect">Label</FormControl.Label>
        <Autocomplete>
          <Autocomplete.Input />
          <Autocomplete.Overlay>
            <Autocomplete.Menu
              selectionVariant="multiple"
              selectedItemIds={selectedItemIds}
              onSelectedChange={newlySelectedItems => {
                // TODO: remove this check when/if we fix the `onSelectedChange` type in PRC
                if (!Array.isArray(newlySelectedItems)) {
                  return
                }


                setSelectedItemIds(newlySelectedItems.map(item => item.id))
              }}
              aria-labelledby="autocompleteLabel-multiselect"
              items={items}
            />
          </Autocomplete.Overlay>
        </Autocomplete>
      </FormControl>
      {selectedItemIds.length > 0 && (
        <div style={{marginTop: '1rem'}}>
          Selected items:
          <ul style={{marginTop: 0}}>
            {items
              .filter(item => selectedItemIds.includes(item.id))
              .map(item => (
                <li key={item.id}>{item.text}</li>
              ))}
          </ul>
        </div>
      )}
    </>
  )
}


const items = [
  {text: 'Components', id: '0'},
  {text: 'Figma', id: '1'},
  {text: 'Design patterns', id: '2'},
  {text: 'Design tokens', id: '3'},
  {text: 'Icons', id: '4'},
  {text: 'Rails', id: '5'},
  {text: 'React', id: '6'},
]

import React from 'react'
import {Autocomplete, FormControl} from '@primer/react'

export default function Multiselect() {
  const [selectedItemIds, setSelectedItemIds] = React.useState<Array<string>>([])

  return (
    <>
      <FormControl>
        <FormControl.Label id="autocompleteLabel-multiselect">Label</FormControl.Label>
        <Autocomplete>
          <Autocomplete.Input />
          <Autocomplete.Overlay>
            <Autocomplete.Menu
              selectionVariant="multiple"
              selectedItemIds={selectedItemIds}
              onSelectedChange={newlySelectedItems => {
                // TODO: remove this check when/if we fix the `onSelectedChange` type in PRC
                if (!Array.isArray(newlySelectedItems)) {
                  return
                }

                setSelectedItemIds(newlySelectedItems.map(item => item.id))
              }}
              aria-labelledby="autocompleteLabel-multiselect"
              items={items}
            />
          </Autocomplete.Overlay>
        </Autocomplete>
      </FormControl>
      {selectedItemIds.length > 0 && (
        <div style={{marginTop: '1rem'}}>
          Selected items:
          <ul style={{marginTop: 0}}>
            {items
              .filter(item => selectedItemIds.includes(item.id))
              .map(item => (
                <li key={item.id}>{item.text}</li>
              ))}
          </ul>
        </div>
      )}
    </>
  )
}

const items = [
  {text: 'Components', id: '0'},
  {text: 'Figma', id: '1'},
  {text: 'Design patterns', id: '2'},
  {text: 'Design tokens', id: '3'},
  {text: 'Icons', id: '4'},
  {text: 'Rails', id: '5'},
  {text: 'React', id: '6'},
]

Multi-select with tokens for selected items

Label

import React from 'react'
import {Autocomplete, FormControl, TextInputWithTokens} from '@primer/react'


export default function MultiselectTokens() {
  const [tokens, setTokens] = React.useState<Array<{text: string; id: string}>>([])
  const selectedTokenIds = tokens.map(token => token.id)
  const [selectedItemIds, setSelectedItemIds] = React.useState<string[]>(selectedTokenIds)
  const onTokenRemove: (tokenId: string | number) => void = tokenId => {
    setTokens(tokens.filter(token => token.id !== tokenId))
    setSelectedItemIds(selectedItemIds.filter(id => id !== tokenId))
  }


  return (
    <FormControl>
      <FormControl.Label id="autocompleteLabel-multiselect-tokens">Label</FormControl.Label>
      <Autocomplete>
        <Autocomplete.Input as={TextInputWithTokens} tokens={tokens} onTokenRemove={onTokenRemove} />
        <Autocomplete.Overlay>
          <Autocomplete.Menu
            selectionVariant="multiple"
            selectedItemIds={selectedItemIds}
            onSelectedChange={newlySelectedItems => {
              if (!Array.isArray(newlySelectedItems)) {
                return
              }


              setSelectedItemIds(newlySelectedItems.map(item => item.id))


              if (newlySelectedItems.length < selectedItemIds.length) {
                const newlySelectedItemIds = newlySelectedItems.map(({id}) => id)
                const removedItemIds = selectedTokenIds.filter(id => !newlySelectedItemIds.includes(id))


                for (const removedItemId of removedItemIds) {
                  onTokenRemove(removedItemId)
                }


                return
              }


              setTokens(newlySelectedItems.map(({id, text}) => ({id, text})))
            }}
            aria-labelledby="autocompleteLabel-multiselect-tokens"
            items={items}
          />
        </Autocomplete.Overlay>
      </Autocomplete>
    </FormControl>
  )
}


const items = [
  {text: 'Components', id: '0'},
  {text: 'Figma', id: '1'},
  {text: 'Design patterns', id: '2'},
  {text: 'Design tokens', id: '3'},
  {text: 'Icons', id: '4'},
  {text: 'Rails', id: '5'},
  {text: 'React', id: '6'},
]

import React from 'react'
import {Autocomplete, FormControl, TextInputWithTokens} from '@primer/react'

export default function MultiselectTokens() {
  const [tokens, setTokens] = React.useState<Array<{text: string; id: string}>>([])
  const selectedTokenIds = tokens.map(token => token.id)
  const [selectedItemIds, setSelectedItemIds] = React.useState<string[]>(selectedTokenIds)
  const onTokenRemove: (tokenId: string | number) => void = tokenId => {
    setTokens(tokens.filter(token => token.id !== tokenId))
    setSelectedItemIds(selectedItemIds.filter(id => id !== tokenId))
  }

  return (
    <FormControl>
      <FormControl.Label id="autocompleteLabel-multiselect-tokens">Label</FormControl.Label>
      <Autocomplete>
        <Autocomplete.Input as={TextInputWithTokens} tokens={tokens} onTokenRemove={onTokenRemove} />
        <Autocomplete.Overlay>
          <Autocomplete.Menu
            selectionVariant="multiple"
            selectedItemIds={selectedItemIds}
            onSelectedChange={newlySelectedItems => {
              if (!Array.isArray(newlySelectedItems)) {
                return
              }

              setSelectedItemIds(newlySelectedItems.map(item => item.id))

              if (newlySelectedItems.length < selectedItemIds.length) {
                const newlySelectedItemIds = newlySelectedItems.map(({id}) => id)
                const removedItemIds = selectedTokenIds.filter(id => !newlySelectedItemIds.includes(id))

                for (const removedItemId of removedItemIds) {
                  onTokenRemove(removedItemId)
                }

                return
              }

              setTokens(newlySelectedItems.map(({id, text}) => ({id, text})))
            }}
            aria-labelledby="autocompleteLabel-multiselect-tokens"
            items={items}
          />
        </Autocomplete.Overlay>
      </Autocomplete>
    </FormControl>
  )
}

const items = [
  {text: 'Components', id: '0'},
  {text: 'Figma', id: '1'},
  {text: 'Design patterns', id: '2'},
  {text: 'Design tokens', id: '3'},
  {text: 'Icons', id: '4'},
  {text: 'Rails', id: '5'},
  {text: 'React', id: '6'},
]

Adding new items from input

When the user isn't limited to a pre-defined list, an additional menu item can be added to select the value they typed.

Label

import {Autocomplete, FormControl} from '@primer/react'
import React from 'react'


export default function Default() {
  const [inputValue, setInputValue] = React.useState<string>('')


  return (
    <FormControl>
      <FormControl.Label id="autocompleteLabel-add-new">Label</FormControl.Label>
      <Autocomplete>
        <Autocomplete.Input
          value={inputValue}
          onChange={e => {
            setInputValue(e.currentTarget.value)
          }}
        />
        <Autocomplete.Overlay>
          <Autocomplete.Menu
            selectedItemIds={[]}
            aria-labelledby="autocompleteLabel-add-new"
            addNewItem={
              inputValue && !items.map(item => item.text).includes(inputValue)
                ? {
                    text: inputValue,
                    id: inputValue,
                    // `handleAddItem` callback isn't needed for this specific example,
                    // but it's included here to show that it exists
                    handleAddItem: selectedItem => {
                      // eslint-disable-next-line no-console
                      console.log('added item:', selectedItem)
                      return
                    },
                  }
                : undefined
            }
            items={items}
          />
        </Autocomplete.Overlay>
      </Autocomplete>
    </FormControl>
  )
}


const items = [
  {text: 'Components', id: '0'},
  {text: 'Figma', id: '1'},
  {text: 'Design patterns', id: '2'},
  {text: 'Design tokens', id: '3'},
  {text: 'Icons', id: '4'},
  {text: 'Rails', id: '5'},
  {text: 'React', id: '6'},
]

import {Autocomplete, FormControl} from '@primer/react'
import React from 'react'

export default function Default() {
  const [inputValue, setInputValue] = React.useState<string>('')

  return (
    <FormControl>
      <FormControl.Label id="autocompleteLabel-add-new">Label</FormControl.Label>
      <Autocomplete>
        <Autocomplete.Input
          value={inputValue}
          onChange={e => {
            setInputValue(e.currentTarget.value)
          }}
        />
        <Autocomplete.Overlay>
          <Autocomplete.Menu
            selectedItemIds={[]}
            aria-labelledby="autocompleteLabel-add-new"
            addNewItem={
              inputValue && !items.map(item => item.text).includes(inputValue)
                ? {
                    text: inputValue,
                    id: inputValue,
                    // `handleAddItem` callback isn't needed for this specific example,
                    // but it's included here to show that it exists
                    handleAddItem: selectedItem => {
                      // eslint-disable-next-line no-console
                      console.log('added item:', selectedItem)
                      return
                    },
                  }
                : undefined
            }
            items={items}
          />
        </Autocomplete.Overlay>
      </Autocomplete>
    </FormControl>
  )
}

const items = [
  {text: 'Components', id: '0'},
  {text: 'Figma', id: '1'},
  {text: 'Design patterns', id: '2'},
  {text: 'Design tokens', id: '3'},
  {text: 'Icons', id: '4'},
  {text: 'Rails', id: '5'},
  {text: 'React', id: '6'},
]

A loading indicator should be displayed while the data for the list of options is being populated. The loading indicator helps the user understand that the list is not empty, it's just not done loading.

Label

import {Autocomplete, FormControl} from '@primer/react'
import React from 'react'


export default function Loading() {
  return (
    <FormControl>
      <FormControl.Label id="autocompleteLabel-loading">Label</FormControl.Label>
      <Autocomplete>
        <Autocomplete.Input />
        <Autocomplete.Overlay>
          <Autocomplete.Menu loading selectedItemIds={[]} aria-labelledby="autocompleteLabel-loading" items={[]} />
        </Autocomplete.Overlay>
      </Autocomplete>
    </FormControl>
  )
}

import {Autocomplete, FormControl} from '@primer/react'
import React from 'react'

export default function Loading() {
  return (
    <FormControl>
      <FormControl.Label id="autocompleteLabel-loading">Label</FormControl.Label>
      <Autocomplete>
        <Autocomplete.Input />
        <Autocomplete.Overlay>
          <Autocomplete.Menu loading selectedItemIds={[]} aria-labelledby="autocompleteLabel-loading" items={[]} />
        </Autocomplete.Overlay>
      </Autocomplete>
    </FormControl>
  )
}

More code examples

See the Autocomplete Storybook stories.

Props

Autocomplete

Name	Default	Description
children		`React.ReactNode`
id		`string` May be used to customize how the ID is set on the text input to be used by ARIA attributes on related elements.

Autocomplete.Input

Name	Default	Description
as	`TextInput`	`React.ElementType`
openOnFocus Deprecated	`false`	`boolean` Whether the associated autocomplete menu should open on an input focus event

See TextInput for more prop options

Autocomplete.Overlay

Name	Default	Description
menuAnchorRef		`React.RefObject<HTMLElement>`
children		`React.ReactNode`
overlayProps Deprecated		`Partial<OverlayProps>` Props to be spread on the internal `Overlay` component.

See Overlay for more prop options

Name	Default	Description
items Required		`T[]` The options for field values that are displayed in the dropdown menu. One or more may be selected depending on the value of the `selectionVariant` prop.
selectedItemIds Required		`string[]` The IDs of the selected items
aria-labelledby Required		`string`
addNewItem		`Omit<T, 'id' \| 'leadingVisual' \| 'onAction'> & { handleAddItem: (item: Omit<T, 'leadingVisual' \| 'onAction'>) => void; }` A menu item that is used to allow users make a selection that is not available in the array passed to the `items` prop. This menu item gets appended to the end of the list of options.
emptyStateText		`React.ReactNode \| false` The text that appears in the menu when there are no options in the array passed to the `items` prop.
filterFn		`(item: T, i: number) => boolean` A custom function used to filter the options in the array passed to the `items` prop. By default, we filter out items that don't match the value of the autocomplete text input. The default filter is not case-sensitive.
loading		`boolean` Whether the data is loading for the menu items
sortOnCloseFn		`(itemIdA: string \| number, itemIdB: string \| number) => number` The sort function that is applied to the options in the array passed to the `items` prop after the user closes the menu. By default, selected items are sorted to the top after the user closes the menu.
selectionVariant		`'single' \| 'multiple'` Whether there can be one item selected from the menu or multiple items selected from the menu
onOpenChange		`(open: boolean) => void` Function that gets called when the menu is opened or closed
onSelectedChange		`(item: T \| T[]) => void` The function that is called when an item in the list is selected or deselected
customScrollContainerRef		`React.MutableRefObject<HTMLElement \| null>` If the menu is rendered in a scrolling element other than the `Autocomplete.Overlay` component, pass the ref of that element to `customScrollContainerRef` to ensure the container automatically scrolls when the user highlights an item in the menu that is outside the scroll container