alpha

useSearchAutocomplete

Provides the behavior and accessibility implementation for a search autocomplete component. A search autocomplete combines a combobox with a searchfield, allowing users to filter a list of options to items matching a query.

install	`yarn add @react-aria/autocomplete`
version	3.0.0-alpha.36
usage	`import {useSearchAutocomplete} from '@react-aria/autocomplete'`

View repository

GitHub

View package

NPM

API#

useSearchAutocomplete<T>(
  (props: AriaSearchAutocompleteOptions<T>,
  , state: ComboBoxState<T>
)): SearchAutocompleteAria<T>

Features#

Autocomplete for search fields can be implemented using the <datalist> HTML element, but this has limited functionality and behaves differently across browsers. useSearchAutocomplete helps achieve accessible search field and autocomplete components that can be styled as needed.

Support for filtering a list of options by typing
Support for selecting a single option
Support for disabled options
Support for groups of items in sections
Support for custom user input values
Support for controlled and uncontrolled options, selection, input value, and open state
Support for custom filter functions
Async loading and infinite scrolling support
Support for use with virtualized lists
Exposed to assistive technology as a combobox with ARIA
Labeling support for accessibility
Required and invalid states exposed to assistive technology via ARIA
Support for mouse, touch, and keyboard interactions
Keyboard support for opening the list box using the arrow keys, including automatically focusing the first or last item accordingly
Support for opening the list box when typing, on focus, or manually
Handles virtual clicks on the input from touch screen readers to toggle the list box
Virtual focus management for list box option navigation
Hides elements outside the input and list box from assistive technology while the list box is open in a portal
Custom localized announcements for option focusing, filtering, and selection using an ARIA live region to work around VoiceOver bugs

Anatomy#

A search autocomplete consists of a label, an input which displays the current value, and a list box popup. Users can type within the input to see search suggestions within the list box. The list box popup may be opened by a variety of input field interactions specified by the menuTrigger prop provided to useSearchAutocomplete. useSearchAutocomplete handles exposing the correct ARIA attributes for accessibility for each of the elements comprising the search autocomplete. It should be combined with useListBox, which handles the implementation of the popup list box.

useSearchAutocomplete returns props that you should spread onto the appropriate elements:

Name	Type	Description
`labelProps`	`DOMAttributes`	Props for the label element.
`inputProps`	`InputHTMLAttributes<HTMLInputElement>`	Props for the search input element.
`listBoxProps`	`AriaListBoxOptions<T>`	Props for the list box, to be passed to useListBox.
`clearButtonProps`	`AriaButtonProps`	Props for the search input's clear button.
`descriptionProps`	`DOMAttributes`	Props for the search autocomplete description element, if any.
`errorMessageProps`	`DOMAttributes`	Props for the search autocomplete error message element, if any.
`isInvalid`	`boolean`	Whether the input value is invalid.
`validationErrors`	`string[]`	The current error messages for the input if it is invalid, otherwise an empty array.
`validationDetails`	`ValidityState`	The native validation details for the input.

State is managed by the useComboBoxState hook from @react-stately/combobox. The state object should be passed as an option to useSearchAutocomplete.

If the search field does not have a visible label, an aria-label or aria-labelledby prop must be provided instead to identify it to assistive technology.

State management#

useSearchAutocomplete requires knowledge of the options in order to handle keyboard navigation and other interactions. It does this using the Collection interface, which is a generic interface to access sequential unique keyed data. You can implement this interface yourself, e.g. by using a prop to pass a list of item objects, but useComboBoxState from @react-stately/combobox implements a JSX based interface for building collections instead. See Collection Components for more information, and Collection Interface for internal details.

In addition, useComboBoxState manages the state necessary for single selection and exposes a SelectionManager, which makes use of the collection to provide an interface to update the selection state. It also holds state to track if the popup is open, if the search field is focused, and the current input value. For more information about selection, see Selection.

Example#

This example uses an <input> element for the search field. A "contains" filter function is obtained from useFilter and is passed to useComboBoxState so that the list box can be filtered based on the option text and the current input text.

The list box popup should use the same Popover and ListBox components created with usePopover and useListBox that you may already have in your component library or application. These can be shared with other components such as a Select created with useSelect or a Dialog popover created with useDialog. The code for these components is also included below in the collapsed sections.

In addition, see useListBox for examples of sections (option groups), and more complex options.

import {Item} from '@react-stately/collections';
import {useButton} from '@react-aria/button';
import {useComboBoxState} from '@react-stately/combobox';
import {useSearchAutocomplete} from '@react-aria/autocomplete';
import {useFilter} from '@react-aria/i18n';

// Reuse the ListBox and Popover from your component library. See below for details.
import {ListBox, Popover} from 'your-component-library';

function SearchAutocomplete(props) {
  // Setup filter function and state.
  let { contains } = useFilter({ sensitivity: 'base' });
  let state = useComboBoxState({ ...props, defaultFilter: contains });

  // Setup refs and get props for child elements.
  let inputRef = React.useRef(null);
  let listBoxRef = React.useRef(null);
  let popoverRef = React.useRef(null);
  let buttonRef = React.useRef(null);

  let { inputProps, listBoxProps, labelProps, clearButtonProps } =
    useSearchAutocomplete(
      {
        ...props,
        popoverRef,
        listBoxRef,
        inputRef
      },
      state
    );

  let { buttonProps } = useButton(clearButtonProps, buttonRef);

  return (
    <div style={{ display: 'inline-flex', flexDirection: 'column' }}>
      <label {...labelProps}>{props.label}</label>
      <div style={{ position: 'relative', display: 'inline-block' }}>
        <input
          {...inputProps}
          ref={inputRef}
          style={{
            height: 24,
            boxSizing: 'border-box',
            marginRight: 0,
            fontSize: 16
          }}
        />
        {state.inputValue !== '' &&
          <button {...buttonProps} ref={buttonRef}>❎</button>}
        {state.isOpen &&
          (
            <Popover
              state={state}
              triggerRef={inputRef}
              popoverRef={popoverRef}
              isNonModal
              placement="bottom start"
            >
              <ListBox
                {...listBoxProps}
                listBoxRef={listBoxRef}
                state={state}
              />
            </Popover>
          )}
      </div>
    </div>
  );
}

<SearchAutocomplete label="Search Animals">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</SearchAutocomplete>

import {Item} from '@react-stately/collections';
import {useButton} from '@react-aria/button';
import {useComboBoxState} from '@react-stately/combobox';
import {useSearchAutocomplete} from '@react-aria/autocomplete';
import {useFilter} from '@react-aria/i18n';

// Reuse the ListBox and Popover from your component library. See below for details.
import {ListBox, Popover} from 'your-component-library';

function SearchAutocomplete(props) {
  // Setup filter function and state.
  let { contains } = useFilter({ sensitivity: 'base' });
  let state = useComboBoxState({
    ...props,
    defaultFilter: contains
  });

  // Setup refs and get props for child elements.
  let inputRef = React.useRef(null);
  let listBoxRef = React.useRef(null);
  let popoverRef = React.useRef(null);
  let buttonRef = React.useRef(null);

  let {
    inputProps,
    listBoxProps,
    labelProps,
    clearButtonProps
  } = useSearchAutocomplete(
    {
      ...props,
      popoverRef,
      listBoxRef,
      inputRef
    },
    state
  );

  let { buttonProps } = useButton(
    clearButtonProps,
    buttonRef
  );

  return (
    <div
      style={{
        display: 'inline-flex',
        flexDirection: 'column'
      }}
    >
      <label {...labelProps}>{props.label}</label>
      <div
        style={{
          position: 'relative',
          display: 'inline-block'
        }}
      >
        <input
          {...inputProps}
          ref={inputRef}
          style={{
            height: 24,
            boxSizing: 'border-box',
            marginRight: 0,
            fontSize: 16
          }}
        />
        {state.inputValue !== '' &&
          (
            <button {...buttonProps} ref={buttonRef}>
              ❎
            </button>
          )}
        {state.isOpen &&
          (
            <Popover
              state={state}
              triggerRef={inputRef}
              popoverRef={popoverRef}
              isNonModal
              placement="bottom start"
            >
              <ListBox
                {...listBoxProps}
                listBoxRef={listBoxRef}
                state={state}
              />
            </Popover>
          )}
      </div>
    </div>
  );
}

<SearchAutocomplete label="Search Animals">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</SearchAutocomplete>

import {Item} from '@react-stately/collections';
import {useButton} from '@react-aria/button';
import {useComboBoxState} from '@react-stately/combobox';
import {useSearchAutocomplete} from '@react-aria/autocomplete';
import {useFilter} from '@react-aria/i18n';

// Reuse the ListBox and Popover from your component library. See below for details.
import {
  ListBox,
  Popover
} from 'your-component-library';

function SearchAutocomplete(
  props
) {
  // Setup filter function and state.
  let { contains } =
    useFilter({
      sensitivity: 'base'
    });
  let state =
    useComboBoxState({
      ...props,
      defaultFilter:
        contains
    });

  // Setup refs and get props for child elements.
  let inputRef = React
    .useRef(null);
  let listBoxRef = React
    .useRef(null);
  let popoverRef = React
    .useRef(null);
  let buttonRef = React
    .useRef(null);

  let {
    inputProps,
    listBoxProps,
    labelProps,
    clearButtonProps
  } =
    useSearchAutocomplete(
      {
        ...props,
        popoverRef,
        listBoxRef,
        inputRef
      },
      state
    );

  let { buttonProps } =
    useButton(
      clearButtonProps,
      buttonRef
    );

  return (
    <div
      style={{
        display:
          'inline-flex',
        flexDirection:
          'column'
      }}
    >
      <label
        {...labelProps}
      >
        {props.label}
      </label>
      <div
        style={{
          position:
            'relative',
          display:
            'inline-block'
        }}
      >
        <input
          {...inputProps}
          ref={inputRef}
          style={{
            height: 24,
            boxSizing:
              'border-box',
            marginRight:
              0,
            fontSize: 16
          }}
        />
        {state
              .inputValue !==
            '' &&
          (
            <button
              {...buttonProps}
              ref={buttonRef}
            >
              ❎
            </button>
          )}
        {state.isOpen &&
          (
            <Popover
              state={state}
              triggerRef={inputRef}
              popoverRef={popoverRef}
              isNonModal
              placement="bottom start"
            >
              <ListBox
                {...listBoxProps}
                listBoxRef={listBoxRef}
                state={state}
              />
            </Popover>
          )}
      </div>
    </div>
  );
}

<SearchAutocomplete label="Search Animals">
  <Item key="red panda">
    Red Panda
  </Item>
  <Item key="cat">
    Cat
  </Item>
  <Item key="dog">
    Dog
  </Item>
  <Item key="aardvark">
    Aardvark
  </Item>
  <Item key="kangaroo">
    Kangaroo
  </Item>
  <Item key="snake">
    Snake
  </Item>
</SearchAutocomplete>

The Popover component is used to contain the popup listbox for the SearchAutocomplete. It can be shared between many other components, including Select, Menu, and others. See usePopover for more examples of popovers.

Show code

import type {AriaPopoverProps} from 'react-aria';
import type {OverlayTriggerState} from 'react-stately';
import {usePopover, Overlay, DismissButton} from '@react-aria/overlays';

interface PopoverProps extends AriaPopoverProps {
  children: React.ReactNode,
  state: OverlayTriggerState
}

function Popover({children, state, ...props}: PopoverProps) {
  let {popoverProps} = usePopover(props, state);

  return (
    <Overlay>
      <div
        {...popoverProps}
        ref={props.popoverRef as React.RefObject<HTMLDivElement>}
        style={{
          ...popoverProps.style,
          background: 'lightgray',
          border: '1px solid gray'
        }}>
        {children}
        <DismissButton onDismiss={state.close} />
      </div>
    </Overlay>
  );
}

import type {AriaPopoverProps} from 'react-aria';
import type {OverlayTriggerState} from 'react-stately';
import {
  DismissButton,
  Overlay,
  usePopover
} from '@react-aria/overlays';

interface PopoverProps extends AriaPopoverProps {
  children: React.ReactNode;
  state: OverlayTriggerState;
}

function Popover(
  { children, state, ...props }: PopoverProps
) {
  let { popoverProps } = usePopover(props, state);

  return (
    <Overlay>
      <div
        {...popoverProps}
        ref={props.popoverRef as React.RefObject<
          HTMLDivElement
        >}
        style={{
          ...popoverProps.style,
          background: 'lightgray',
          border: '1px solid gray'
        }}
      >
        {children}
        <DismissButton onDismiss={state.close} />
      </div>
    </Overlay>
  );
}

import type {AriaPopoverProps} from 'react-aria';
import type {OverlayTriggerState} from 'react-stately';
import {
  DismissButton,
  Overlay,
  usePopover
} from '@react-aria/overlays';

interface PopoverProps
  extends
    AriaPopoverProps {
  children:
    React.ReactNode;
  state:
    OverlayTriggerState;
}

function Popover(
  {
    children,
    state,
    ...props
  }: PopoverProps
) {
  let { popoverProps } =
    usePopover(
      props,
      state
    );

  return (
    <Overlay>
      <div
        {...popoverProps}
        ref={props
          .popoverRef as React.RefObject<
            HTMLDivElement
          >}
        style={{
          ...popoverProps
            .style,
          background:
            'lightgray',
          border:
            '1px solid gray'
        }}
      >
        {children}
        <DismissButton
          onDismiss={state
            .close}
        />
      </div>
    </Overlay>
  );
}

ListBox#

The ListBox and Option components are used to show the filtered list of options as the user types in the SearchAutocomplete. They can also be shared with other components like a Select. See useListBox for more examples, including sections and more complex items.

Show code

import {useListBox, useOption} from '@react-aria/listbox';

function ListBox(props) {
  let ref = React.useRef(null);
  let { listBoxRef = ref, state } = props;
  let { listBoxProps } = useListBox(props, state, listBoxRef);

  return (
    <ul
      {...listBoxProps}
      ref={listBoxRef}
      style={{
        margin: 0,
        padding: 0,
        listStyle: 'none',
        maxHeight: 150,
        overflow: 'auto',
        minWidth: 200
      }}
    >
      {[...state.collection].map((item) => (
        <Option
          key={item.key}
          item={item}
          state={state}
        />
      ))}
    </ul>
  );
}

function Option({ item, state }) {
  let ref = React.useRef(null);
  let { optionProps, isSelected, isFocused, isDisabled } = useOption(
    { key: item.key },
    state,
    ref
  );

  let backgroundColor;
  let color = 'black';

  if (isSelected) {
    backgroundColor = 'blueviolet';
    color = 'white';
  } else if (isFocused) {
    backgroundColor = 'gray';
  } else if (isDisabled) {
    backgroundColor = 'transparent';
    color = 'gray';
  }

  return (
    <li
      {...optionProps}
      ref={ref}
      style={{
        background: backgroundColor,
        color: color,
        padding: '2px 5px',
        outline: 'none',
        cursor: 'pointer'
      }}
    >
      {item.rendered}
    </li>
  );
}

import {useListBox, useOption} from '@react-aria/listbox';

function ListBox(props) {
  let ref = React.useRef(null);
  let { listBoxRef = ref, state } = props;
  let { listBoxProps } = useListBox(
    props,
    state,
    listBoxRef
  );

  return (
    <ul
      {...listBoxProps}
      ref={listBoxRef}
      style={{
        margin: 0,
        padding: 0,
        listStyle: 'none',
        maxHeight: 150,
        overflow: 'auto',
        minWidth: 200
      }}
    >
      {[...state.collection].map((item) => (
        <Option
          key={item.key}
          item={item}
          state={state}
        />
      ))}
    </ul>
  );
}

function Option({ item, state }) {
  let ref = React.useRef(null);
  let { optionProps, isSelected, isFocused, isDisabled } =
    useOption({ key: item.key }, state, ref);

  let backgroundColor;
  let color = 'black';

  if (isSelected) {
    backgroundColor = 'blueviolet';
    color = 'white';
  } else if (isFocused) {
    backgroundColor = 'gray';
  } else if (isDisabled) {
    backgroundColor = 'transparent';
    color = 'gray';
  }

  return (
    <li
      {...optionProps}
      ref={ref}
      style={{
        background: backgroundColor,
        color: color,
        padding: '2px 5px',
        outline: 'none',
        cursor: 'pointer'
      }}
    >
      {item.rendered}
    </li>
  );
}

import {
  useListBox,
  useOption
} from '@react-aria/listbox';

function ListBox(props) {
  let ref = React.useRef(
    null
  );
  let {
    listBoxRef = ref,
    state
  } = props;
  let { listBoxProps } =
    useListBox(
      props,
      state,
      listBoxRef
    );

  return (
    <ul
      {...listBoxProps}
      ref={listBoxRef}
      style={{
        margin: 0,
        padding: 0,
        listStyle:
          'none',
        maxHeight: 150,
        overflow: 'auto',
        minWidth: 200
      }}
    >
      {[
        ...state
          .collection
      ].map((item) => (
        <Option
          key={item.key}
          item={item}
          state={state}
        />
      ))}
    </ul>
  );
}

function Option(
  { item, state }
) {
  let ref = React.useRef(
    null
  );
  let {
    optionProps,
    isSelected,
    isFocused,
    isDisabled
  } = useOption(
    { key: item.key },
    state,
    ref
  );

  let backgroundColor;
  let color = 'black';

  if (isSelected) {
    backgroundColor =
      'blueviolet';
    color = 'white';
  } else if (isFocused) {
    backgroundColor =
      'gray';
  } else if (
    isDisabled
  ) {
    backgroundColor =
      'transparent';
    color = 'gray';
  }

  return (
    <li
      {...optionProps}
      ref={ref}
      style={{
        background:
          backgroundColor,
        color: color,
        padding:
          '2px 5px',
        outline: 'none',
        cursor: 'pointer'
      }}
    >
      {item.rendered}
    </li>
  );
}

Usage#

The following examples show how to use the SearchAutocomplete component created in the above example.

Uncontrolled#

The following example shows how you would create an uncontrolled SearchAutocomplete. The input value, selected option, and open state is completely uncontrolled.

<SearchAutocomplete label="Search Animals">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</SearchAutocomplete>

<SearchAutocomplete label="Search Animals">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</SearchAutocomplete>

<SearchAutocomplete label="Search Animals">
  <Item key="red panda">
    Red Panda
  </Item>
  <Item key="cat">
    Cat
  </Item>
  <Item key="dog">
    Dog
  </Item>
  <Item key="aardvark">
    Aardvark
  </Item>
  <Item key="kangaroo">
    Kangaroo
  </Item>
  <Item key="snake">
    Snake
  </Item>
</SearchAutocomplete>

Dynamic collections#

SearchAutocomplete follows the Collection Components API, accepting both static and dynamic collections. The examples above show static collections, which can be used when the full list of options is known ahead of time. Dynamic collections, as shown below, can be used when the options come from an external data source such as an API call, or update over time.

As seen below, an iterable list of options is passed to the SearchAutocomplete using the defaultItems prop. The input's value is passed to the onSubmit handler, along with a key if the event was triggered by selecting an item from the listbox.

function Example() {
  let options = [
    {id: 1, name: 'Aerospace'},
    {id: 2, name: 'Mechanical'},
    {id: 3, name: 'Civil'},
    {id: 4, name: 'Biomedical'},
    {id: 5, name: 'Nuclear'},
    {id: 6, name: 'Industrial'},
    {id: 7, name: 'Chemical'},
    {id: 8, name: 'Agricultural'},
    {id: 9, name: 'Electrical'}
  ];
  let [major, setMajor] = React.useState(null);

  let onSubmit = (value, key) => {
    if (value) {
      setMajor(value);
    } else if (key) {
      setMajor(options.find(o => o.id === key).name);
    }
  };

  return (
    <>
      <SearchAutocomplete
        label="Search engineering majors"
        defaultItems={options}
        onSubmit={onSubmit}>
        {(item) => <Item>{item.name}</Item>}
      </SearchAutocomplete>
      <p>Results for: {major}</p>
    </>
  );
}

function Example() {
  let options = [
    {id: 1, name: 'Aerospace'},
    {id: 2, name: 'Mechanical'},
    {id: 3, name: 'Civil'},
    {id: 4, name: 'Biomedical'},
    {id: 5, name: 'Nuclear'},
    {id: 6, name: 'Industrial'},
    {id: 7, name: 'Chemical'},
    {id: 8, name: 'Agricultural'},
    {id: 9, name: 'Electrical'}
  ];
  let [major, setMajor] = React.useState(null);

  let onSubmit = (value, key) => {
    if (value) {
      setMajor(value);
    } else if (key) {
      setMajor(options.find(o => o.id === key).name);
    }
  };

  return (
    <>
      <SearchAutocomplete
        label="Search engineering majors"
        defaultItems={options}
        onSubmit={onSubmit}>
        {(item) => <Item>{item.name}</Item>}
      </SearchAutocomplete>
      <p>Results for: {major}</p>
    </>
  );
}

function Example() {
  let options = [
    {
      id: 1,
      name: 'Aerospace'
    },
    {
      id: 2,
      name: 'Mechanical'
    },
    {
      id: 3,
      name: 'Civil'
    },
    {
      id: 4,
      name: 'Biomedical'
    },
    {
      id: 5,
      name: 'Nuclear'
    },
    {
      id: 6,
      name: 'Industrial'
    },
    {
      id: 7,
      name: 'Chemical'
    },
    {
      id: 8,
      name:
        'Agricultural'
    },
    {
      id: 9,
      name: 'Electrical'
    }
  ];
  let [major, setMajor] =
    React.useState(null);

  let onSubmit = (
    value,
    key
  ) => {
    if (value) {
      setMajor(value);
    } else if (key) {
      setMajor(
        options.find(
          (o) =>
            o.id === key
        ).name
      );
    }
  };

  return (
    <>
      <SearchAutocomplete
        label="Search engineering majors"
        defaultItems={options}
        onSubmit={onSubmit}
      >
        {(item) => (
          <Item>
            {item.name}
          </Item>
        )}
      </SearchAutocomplete>
      <p>
        Results for:{' '}
        {major}
      </p>
    </>
  );
}

Custom filtering#

By default, useComboBoxState uses the filter function passed to the defaultFilter prop (in the above example, a "contains" function from useFilter). The filter function can be overridden by users of the SearchAutocomplete component by using the items prop to control the filtered list. When items is provided rather than defaultItems, useComboBoxState does no filtering of its own.

The following example makes the inputValue controlled, and updates the filtered list that is passed to the items prop when the input changes value.

function Example() {
  let options = [
    {id: 1, email: 'fake@email.com'},
    {id: 2, email: 'anotherfake@email.com'},
    {id: 3, email: 'bob@email.com'},
    {id: 4, email: 'joe@email.com'},
    {id: 5, email: 'yourEmail@email.com'},
    {id: 6, email: 'valid@email.com'},
    {id: 7, email: 'spam@email.com'},
    {id: 8, email: 'newsletter@email.com'},
    {id: 9, email: 'subscribe@email.com'}
  ];

  let {startsWith} = useFilter({sensitivity: 'base'});
  let [filterValue, setFilterValue] = React.useState('');
  let filteredItems = React.useMemo(
    () => options.filter((item) => startsWith(item.email, filterValue)),
    [options, filterValue]
  );

  return (
    <SearchAutocomplete
      label="To:"
      items={filteredItems}
      inputValue={filterValue}
      onInputChange={setFilterValue}>
      {(item) => <Item>{item.email}</Item>}
    </SearchAutocomplete>
  );
}

function Example() {
  let options = [
    { id: 1, email: 'fake@email.com' },
    { id: 2, email: 'anotherfake@email.com' },
    { id: 3, email: 'bob@email.com' },
    { id: 4, email: 'joe@email.com' },
    { id: 5, email: 'yourEmail@email.com' },
    { id: 6, email: 'valid@email.com' },
    { id: 7, email: 'spam@email.com' },
    { id: 8, email: 'newsletter@email.com' },
    { id: 9, email: 'subscribe@email.com' }
  ];

  let { startsWith } = useFilter({ sensitivity: 'base' });
  let [filterValue, setFilterValue] = React.useState('');
  let filteredItems = React.useMemo(
    () =>
      options.filter((item) =>
        startsWith(item.email, filterValue)
      ),
    [options, filterValue]
  );

  return (
    <SearchAutocomplete
      label="To:"
      items={filteredItems}
      inputValue={filterValue}
      onInputChange={setFilterValue}
    >
      {(item) => <Item>{item.email}</Item>}
    </SearchAutocomplete>
  );
}

function Example() {
  let options = [
    {
      id: 1,
      email:
        'fake@email.com'
    },
    {
      id: 2,
      email:
        'anotherfake@email.com'
    },
    {
      id: 3,
      email:
        'bob@email.com'
    },
    {
      id: 4,
      email:
        'joe@email.com'
    },
    {
      id: 5,
      email:
        'yourEmail@email.com'
    },
    {
      id: 6,
      email:
        'valid@email.com'
    },
    {
      id: 7,
      email:
        'spam@email.com'
    },
    {
      id: 8,
      email:
        'newsletter@email.com'
    },
    {
      id: 9,
      email:
        'subscribe@email.com'
    }
  ];

  let { startsWith } =
    useFilter({
      sensitivity: 'base'
    });
  let [
    filterValue,
    setFilterValue
  ] = React.useState('');
  let filteredItems =
    React.useMemo(
      () =>
        options.filter((
          item
        ) =>
          startsWith(
            item.email,
            filterValue
          )
        ),
      [
        options,
        filterValue
      ]
    );

  return (
    <SearchAutocomplete
      label="To:"
      items={filteredItems}
      inputValue={filterValue}
      onInputChange={setFilterValue}
    >
      {(item) => (
        <Item>
          {item.email}
        </Item>
      )}
    </SearchAutocomplete>
  );
}

Fully controlled#

The following example shows how you would create a controlled SearchAutocomplete, by controlling the input value (inputValue) and the autocomplete options (items). By passing in inputValue and items to the SearchAutocomplete you can control exactly what your SearchAutocomplete should display. For example, note that the item filtering for the controlled SearchAutocomplete below now follows a "starts with" filter strategy, accomplished by controlling the exact set of items available to the SearchAutocomplete whenever the input value updates.

function ControlledSearchAutocomplete() {
  let optionList = [
    { name: 'Red Panda', id: '1' },
    { name: 'Cat', id: '2' },
    { name: 'Dog', id: '3' },
    { name: 'Aardvark', id: '4' },
    { name: 'Kangaroo', id: '5' },
    { name: 'Snake', id: '6' }
  ];

  // Store SearchAutocomplete input value, selected option, open state, and items
  // in a state tracker
  let [fieldState, setFieldState] = React.useState({
    inputValue: '',
    items: optionList
  });

  // Implement custom filtering logic and control what items are
  // available to the SearchAutocomplete.
  let { startsWith } = useFilter({ sensitivity: 'base' });

  // Specify how each of the SearchAutocomplete values should change when an
  // option is selected from the list box
  let onSubmit = (value, key) => {
    setFieldState((prevState) => {
      let selectedItem = prevState.items.find((option) => option.id === key);
      return ({
        inputValue: selectedItem?.name ?? '',
        items: optionList.filter((item) =>
          startsWith(item.name, selectedItem?.name ?? '')
        )
      });
    });
  };

  // Specify how each of the SearchAutocomplete values should change when the input
  // field is altered by the user
  let onInputChange = (value) => {
    setFieldState((prevState) => ({
      inputValue: value,
      items: optionList.filter((item) => startsWith(item.name, value))
    }));
  };

  // Show entire list if user opens the menu manually
  let onOpenChange = (isOpen, menuTrigger) => {
    if (menuTrigger === 'manual' && isOpen) {
      setFieldState((prevState) => ({
        inputValue: prevState.inputValue,
        items: optionList
      }));
    }
  };

  // Pass each controlled prop to useSearchAutocomplete along with their
  // change handlers
  return (
    <SearchAutocomplete
      label="Search Animals"
      items={fieldState.items}
      inputValue={fieldState.inputValue}
      onOpenChange={onOpenChange}
      onSubmit={onSubmit}
      onInputChange={onInputChange}
    >
      {(item) => <Item>{item.name}</Item>}
    </SearchAutocomplete>
  );
}

<ControlledSearchAutocomplete />

function ControlledSearchAutocomplete() {
  let optionList = [
    { name: 'Red Panda', id: '1' },
    { name: 'Cat', id: '2' },
    { name: 'Dog', id: '3' },
    { name: 'Aardvark', id: '4' },
    { name: 'Kangaroo', id: '5' },
    { name: 'Snake', id: '6' }
  ];

  // Store SearchAutocomplete input value, selected option, open state, and items
  // in a state tracker
  let [fieldState, setFieldState] = React.useState({
    inputValue: '',
    items: optionList
  });

  // Implement custom filtering logic and control what items are
  // available to the SearchAutocomplete.
  let { startsWith } = useFilter({ sensitivity: 'base' });

  // Specify how each of the SearchAutocomplete values should change when an
  // option is selected from the list box
  let onSubmit = (value, key) => {
    setFieldState((prevState) => {
      let selectedItem = prevState.items.find((option) =>
        option.id === key
      );
      return ({
        inputValue: selectedItem?.name ?? '',
        items: optionList.filter((item) =>
          startsWith(item.name, selectedItem?.name ?? '')
        )
      });
    });
  };

  // Specify how each of the SearchAutocomplete values should change when the input
  // field is altered by the user
  let onInputChange = (value) => {
    setFieldState((prevState) => ({
      inputValue: value,
      items: optionList.filter((item) =>
        startsWith(item.name, value)
      )
    }));
  };

  // Show entire list if user opens the menu manually
  let onOpenChange = (isOpen, menuTrigger) => {
    if (menuTrigger === 'manual' && isOpen) {
      setFieldState((prevState) => ({
        inputValue: prevState.inputValue,
        items: optionList
      }));
    }
  };

  // Pass each controlled prop to useSearchAutocomplete along with their
  // change handlers
  return (
    <SearchAutocomplete
      label="Search Animals"
      items={fieldState.items}
      inputValue={fieldState.inputValue}
      onOpenChange={onOpenChange}
      onSubmit={onSubmit}
      onInputChange={onInputChange}
    >
      {(item) => <Item>{item.name}</Item>}
    </SearchAutocomplete>
  );
}

<ControlledSearchAutocomplete />

function ControlledSearchAutocomplete() {
  let optionList = [
    {
      name: 'Red Panda',
      id: '1'
    },
    {
      name: 'Cat',
      id: '2'
    },
    {
      name: 'Dog',
      id: '3'
    },
    {
      name: 'Aardvark',
      id: '4'
    },
    {
      name: 'Kangaroo',
      id: '5'
    },
    {
      name: 'Snake',
      id: '6'
    }
  ];

  // Store SearchAutocomplete input value, selected option, open state, and items
  // in a state tracker
  let [
    fieldState,
    setFieldState
  ] = React.useState({
    inputValue: '',
    items: optionList
  });

  // Implement custom filtering logic and control what items are
  // available to the SearchAutocomplete.
  let { startsWith } =
    useFilter({
      sensitivity: 'base'
    });

  // Specify how each of the SearchAutocomplete values should change when an
  // option is selected from the list box
  let onSubmit = (
    value,
    key
  ) => {
    setFieldState(
      (prevState) => {
        let selectedItem =
          prevState.items
            .find(
              (option) =>
                option
                  .id ===
                  key
            );
        return ({
          inputValue:
            selectedItem
              ?.name ??
              '',
          items:
            optionList
              .filter(
                (item) =>
                  startsWith(
                    item
                      .name,
                    selectedItem
                      ?.name ??
                      ''
                  )
              )
        });
      }
    );
  };

  // Specify how each of the SearchAutocomplete values should change when the input
  // field is altered by the user
  let onInputChange = (
    value
  ) => {
    setFieldState(
      (prevState) => ({
        inputValue:
          value,
        items: optionList
          .filter(
            (item) =>
              startsWith(
                item
                  .name,
                value
              )
          )
      })
    );
  };

  // Show entire list if user opens the menu manually
  let onOpenChange = (
    isOpen,
    menuTrigger
  ) => {
    if (
      menuTrigger ===
        'manual' &&
      isOpen
    ) {
      setFieldState(
        (prevState) => ({
          inputValue:
            prevState
              .inputValue,
          items:
            optionList
        })
      );
    }
  };

  // Pass each controlled prop to useSearchAutocomplete along with their
  // change handlers
  return (
    <SearchAutocomplete
      label="Search Animals"
      items={fieldState
        .items}
      inputValue={fieldState
        .inputValue}
      onOpenChange={onOpenChange}
      onSubmit={onSubmit}
      onInputChange={onInputChange}
    >
      {(item) => (
        <Item>
          {item.name}
        </Item>
      )}
    </SearchAutocomplete>
  );
}

<ControlledSearchAutocomplete />

useComboBoxState supports three different menuTrigger prop values:

input (default): SearchAutocomplete menu opens when the user edits the input text.
focus: SearchAutocomplete menu opens when the user focuses the SearchAutocomplete input.
manual: SearchAutocomplete menu only opens when the user presses the trigger button or uses the arrow keys.

The example below has menuTrigger set to focus.

<SearchAutocomplete label="Search Animals" menuTrigger="focus">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</SearchAutocomplete>

<SearchAutocomplete
  label="Search Animals"
  menuTrigger="focus"
>
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</SearchAutocomplete>

<SearchAutocomplete
  label="Search Animals"
  menuTrigger="focus"
>
  <Item key="red panda">
    Red Panda
  </Item>
  <Item key="cat">
    Cat
  </Item>
  <Item key="dog">
    Dog
  </Item>
  <Item key="aardvark">
    Aardvark
  </Item>
  <Item key="kangaroo">
    Kangaroo
  </Item>
  <Item key="snake">
    Snake
  </Item>
</SearchAutocomplete>

Disabled options#

You can disable specific options by providing an array of keys to useComboBoxState via the disabledKeys prop. This will prevent options with matching keys from being pressable and receiving keyboard focus as shown in the example below. Note that you are responsible for the styling of disabled options.

<SearchAutocomplete label="Search Animals" disabledKeys={['cat', 'kangaroo']}>
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</SearchAutocomplete>

<SearchAutocomplete
  label="Search Animals"
  disabledKeys={['cat', 'kangaroo']}
>
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</SearchAutocomplete>

<SearchAutocomplete
  label="Search Animals"
  disabledKeys={[
    'cat',
    'kangaroo'
  ]}
>
  <Item key="red panda">
    Red Panda
  </Item>
  <Item key="cat">
    Cat
  </Item>
  <Item key="dog">
    Dog
  </Item>
  <Item key="aardvark">
    Aardvark
  </Item>
  <Item key="kangaroo">
    Kangaroo
  </Item>
  <Item key="snake">
    Snake
  </Item>
</SearchAutocomplete>

Asynchronous loading#

This example uses the useAsyncList hook to handle asynchronous loading and filtering of data from a server. You may additionally want to display a spinner to indicate the loading state to the user, or support features like infinite scroll to load more data.

import {useAsyncList} from '@react-stately/data';

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

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

  return (
    <SearchAutocomplete
      label="Search Star Wars Characters"
      items={list.items}
      inputValue={list.filterText}
      onInputChange={list.setFilterText}>
      {(item) => <Item key={item.name}>{item.name}</Item>}
    </SearchAutocomplete>
  );
}

import {useAsyncList} from '@react-stately/data';

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

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

  return (
    <SearchAutocomplete
      label="Search Star Wars Characters"
      items={list.items}
      inputValue={list.filterText}
      onInputChange={list.setFilterText}
    >
      {(item) => <Item key={item.name}>{item.name}</Item>}
    </SearchAutocomplete>
  );
}

import {useAsyncList} from '@react-stately/data';

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

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

  return (
    <SearchAutocomplete
      label="Search Star Wars Characters"
      items={list.items}
      inputValue={list
        .filterText}
      onInputChange={list
        .setFilterText}
    >
      {(item) => (
        <Item
          key={item.name}
        >
          {item.name}
        </Item>
      )}
    </SearchAutocomplete>
  );
}

Links#

By default, interacting with an item in a SearchAutocomplete updates the input value. Alternatively, items may be links to another page or website. This can be achieved by passing the href prop to the <Item> component. Interacting with link items navigates to the provided URL and does not update the input value. See the links section in the useListBox docs for details on how to support this.

Internationalization#

useSearchAutocomplete handles some aspects of internationalization automatically. For example, the item focus, count, and selection VoiceOver announcements are localized. You are responsible for localizing all labels and option content that is passed into the autocomplete.

Name	Type	Default	Description
`inputRef`	`RefObject<HTMLInputElement \| null>`	—	The ref for the input element.
`popoverRef`	`RefObject<HTMLDivElement \| null>`	—	The ref for the list box popover.
`listBoxRef`	`RefObject<HTMLElement \| null>`	—	The ref for the list box.
`children`	`CollectionChildren<T>`	—	The contents of the collection.
`keyboardDelegate`	`KeyboardDelegate`	—	An optional keyboard delegate implementation, to override the default.
`layoutDelegate`	`LayoutDelegate`	—	A delegate object that provides layout information for items in the collection. By default this uses the DOM, but this can be overridden to implement things like virtualized scrolling.
`defaultItems`	`Iterable<T>`	—	The list of SearchAutocomplete items (uncontrolled).
`items`	`Iterable<T>`	—	The list of SearchAutocomplete items (controlled).
`onOpenChange`	`( (isOpen: boolean, , menuTrigger?: MenuTriggerAction )) => void`	—	Method that is called when the open state of the menu changes. Returns the new open state and the action that caused the opening of the menu.
`inputValue`	`string`	—	The value of the SearchAutocomplete input (controlled).
`defaultInputValue`	`string`	—	The default value of the SearchAutocomplete input (uncontrolled).
`onInputChange`	`( (value: string )) => void`	—	Handler that is called when the SearchAutocomplete input value changes.
`menuTrigger`	`MenuTriggerAction`	`'input'`	The interaction required to display the SearchAutocomplete menu.
`onSubmit`	`( (value: string \| \| null, , key: Key \| \| null )) => void`	—	Handler that is called when the SearchAutocomplete is submitted. A `value` will be passed if the submission is a custom value (e.g. a user types then presses enter). If the input is a selected item, `value` will be null. A `key` will be passed if the submission is a selected item (e.g. a user clicks or presses enter on an option). If the input is a custom value, `key` will be null.
`disabledKeys`	`Iterable<Key>`	—	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`onClear`	`() => void`	—	Handler that is called when the clear button is pressed.
`isDisabled`	`boolean`	—	Whether the input is disabled.
`isReadOnly`	`boolean`	—	Whether the input can be selected but not changed by the user.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission.
`isInvalid`	`boolean`	—	Whether the input value is invalid.
`validationBehavior`	`'aria' \| 'native'`	`'aria'`	Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
`validate`	`( (value: string )) => ValidationError \| true \| null \| undefined`	—	A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.
`description`	`ReactNode`	—	A description for the field. Provides a hint such as specific requirements for what to choose.
`errorMessage`	`ReactNode \| ( (v: ValidationResult )) => ReactNode`	—	An error message for the field.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent<T> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<T> )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`placeholder`	`string`	—	Temporary text that occupies the text input when it is empty.
`onChange`	`( (value: T )) => void`	—	Handler that is called when the value changes.
`label`	`ReactNode`	—	The content to display as the label.
`aria-activedescendant`	`string`	—	Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application.
`aria-autocomplete`	`'none' \| 'inline' \| 'list' \| 'both'`	—	Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be presented if they are made.
`aria-haspopup`	`boolean \| 'false' \| 'true' \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog'`	—	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`excludeFromTabOrder`	`boolean`	—	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`id`	`string`	—	The element's unique identifier. See MDN.
`autoComplete`	`string`	—	Describes the type of autocomplete functionality the input should provide if any. See MDN.
`maxLength`	`number`	—	The maximum number of characters supported by the input. See MDN.
`minLength`	`number`	—	The minimum number of characters required by the input. See MDN.
`pattern`	`string`	—	Regex pattern that the value of the input must match to be valid. See MDN.
`type`	`'text' \| 'search' \| 'url' \| 'tel' \| 'email' \| 'password' \| string & & {}`	—	The type of input to render. See MDN.
`inputMode`	`'none' \| 'text' \| 'tel' \| 'url' \| 'email' \| 'numeric' \| 'decimal' \| 'search'`	—	Hints at the type of data that might be entered by the user while editing the element or its contents. See MDN.
`name`	`string`	—	The name of the input element, used when submitting an HTML form. See MDN.
`onCopy`	`ClipboardEventHandler<HTMLInputElement>`	—	Handler that is called when the user copies text. See MDN.
`onCut`	`ClipboardEventHandler<HTMLInputElement>`	—	Handler that is called when the user cuts text. See MDN.
`onPaste`	`ClipboardEventHandler<HTMLInputElement>`	—	Handler that is called when the user pastes text. See MDN.
`onCompositionStart`	`CompositionEventHandler<HTMLInputElement>`	—	Handler that is called when a text composition system starts a new text composition session. See MDN.
`onCompositionEnd`	`CompositionEventHandler<HTMLInputElement>`	—	Handler that is called when a text composition system completes or cancels the current text composition session. See MDN.
`onCompositionUpdate`	`CompositionEventHandler<HTMLInputElement>`	—	Handler that is called when a new character is received in the current text composition session. See MDN.
`onSelect`	`ReactEventHandler<HTMLInputElement>`	—	Handler that is called when text in the input is selected. See MDN.
`onBeforeInput`	`FormEventHandler<HTMLInputElement>`	—	Handler that is called when the input value is about to be modified. See MDN.
`onInput`	`FormEventHandler<HTMLInputElement>`	—	Handler that is called when the input value is modified. See MDN.
`aria-errormessage`	`string`	—	Identifies the element that provides an error message for the object.

Name	Type	Description
`current`	`T`

Method	Description
`getKeyBelow( (key: Key )): Key \| null`	Returns the key visually below the given one, or `null` for none.
`getKeyAbove( (key: Key )): Key \| null`	Returns the key visually above the given one, or `null` for none.
`getKeyLeftOf( (key: Key )): Key \| null`	Returns the key visually to the left of the given one, or `null` for none.
`getKeyRightOf( (key: Key )): Key \| null`	Returns the key visually to the right of the given one, or `null` for none.
`getKeyPageBelow( (key: Key )): Key \| null`	Returns the key visually one page below the given one, or `null` for none.
`getKeyPageAbove( (key: Key )): Key \| null`	Returns the key visually one page above the given one, or `null` for none.
`getFirstKey( (key?: Key \| \| null, , global?: boolean )): Key \| null`	Returns the first key, or `null` for none.
`getLastKey( (key?: Key \| \| null, , global?: boolean )): Key \| null`	Returns the last key, or `null` for none.
`getKeyForSearch( (search: string, , fromKey?: Key \| \| null )): Key \| null`	Returns the next key after `fromKey` that matches the given search string, or `null` for none.

A LayoutDelegate provides layout information for collection items.

Method	Description
`getItemRect( (key: Key )): Rect \| null`	Returns a rectangle for the item with the given key.
`getVisibleRect(): Rect`	Returns the visible rectangle of the collection.
`getContentSize(): Size`	Returns the size of the scrollable content in the collection.
`getKeyRange( (from: Key, , to: Key )): Key[]`	Returns a list of keys between `from` and `to`.

Name	Type	Description
`x`	`number`
`y`	`number`
`width`	`number`
`height`	`number`

Name	Type	Description
`width`	`number`
`height`	`number`

'focus'
  | 'input'
  | 'manual'

string | number

CollectionElement<T>
  | CollectionElement<T>[]
  | (
    (item: T
  )) => CollectionElement<T>

SectionElement<T> | ItemElement<T>

ReactElement<SectionProps<T>> | null

Name	Type	Description
`children`	`ItemElement<T> \| ItemElement<T>[] \| ItemRenderer<T>`	Static child items or a function to render children.
`title`	`ReactNode`	Rendered contents of the section, e.g. a header.
`aria-label`	`string`	An accessibility label for the section.
`items`	`Iterable<T>`	Item objects in the section.

ReactElement<ItemProps<T>> | null

Name	Type	Description
`children`	`ReactNode`	Rendered contents of the item or child items.
`title`	`ReactNode`	Rendered contents of the item if `children` contains child items.
`textValue`	`string`	A string representation of the item's contents, used for features like typeahead.
`aria-label`	`string`	An accessibility label for this item.
`childItems`	`Iterable<T>`	A list of child item objects. Used for dynamic collections.
`hasChildItems`	`boolean`	Whether this item has children, even if not loaded yet.
`href`	`Href`	A URL to link to. See MDN.
`hrefLang`	`string`	Hints at the human language of the linked URL. SeeMDN.
`target`	`HTMLAttributeAnchorTarget`	The target window for the link. See MDN.
`rel`	`string`	The relationship between the linked resource and the current page. See MDN.
`download`	`boolean \| string`	Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.
`ping`	`string`	A space-separated list of URLs to ping when the link is followed. See MDN.
`referrerPolicy`	`HTMLAttributeReferrerPolicy`	How much of the referrer to send when following the link. See MDN.
`routerOptions`	`RouterOptions`	Options for the configured client side router.

RouterConfig extends {href: any
} ? H : string

RouterConfig extends {routerOptions: any
} ? O : never

(
  (item: T
)) => ItemElement<T>

'valid' | 'invalid'

string | string[]

Name	Type	Description
`isInvalid`	`boolean`	Whether the input value is invalid.
`validationErrors`	`string[]`	The current error messages for the input if it is invalid, otherwise an empty array.
`validationDetails`	`ValidityState`	The native validation details for the input.

BaseEvent<ReactKeyboardEvent<any>>

SyntheticEvent & {stopPropagation: () => void,
continuePropagation: () => void
}

Properties

Name	Type	Description
`inputValue`	`string`	The current value of the combo box input.
`focusStrategy`	`FocusStrategy \| null`	Controls which item will be auto focused when the menu opens.
`isFocused`	`boolean`	Whether the select is currently focused.
`selectedKey`	`Key \| null`	The key for the currently selected item.
`selectedItem`	`Node<T> \| null`	The value of the currently selected item.
`collection`	`Collection<Node<T>>`	A collection of items in the list.
`disabledKeys`	`Set<Key>`	A set of items that are disabled.
`selectionManager`	`SelectionManager`	A selection manager to read and update multiple selection state.
`isOpen`	`boolean`	Whether the overlay is currently open.
`realtimeValidation`	`ValidationResult`	Realtime validation results, updated as the user edits the value.
`displayValidation`	`ValidationResult`	Currently displayed validation results, updated when the user commits their changes.

Methods

Method	Description
`setInputValue( (value: string )): void`	Sets the value of the combo box input.
`commit(): void`	Selects the currently focused item and updates the input value.
`open( (focusStrategy?: FocusStrategy \| \| null, , trigger?: MenuTriggerAction )): void`	Opens the menu.
`toggle( (focusStrategy?: FocusStrategy \| \| null, , trigger?: MenuTriggerAction )): void`	Toggles the menu.
`revert(): void`	Resets the input value to the previously selected item's text if any and closes the menu.
`setFocused( (isFocused: boolean )): void`	Sets whether the select is focused.
`setSelectedKey( (key: Key \| \| null )): void`	Sets the selected key.
`setOpen( (isOpen: boolean )): void`	Sets whether the overlay is open.
`close(): void`	Closes the overlay.
`updateValidation( (result: ValidationResult )): void`	Updates the current validation result. Not displayed to the user until `commitValidation` is called.
`resetValidation(): void`	Resets the displayed validation state to valid when the user resets the form.
`commitValidation(): void`	Commits the realtime validation so it is displayed to the user.

'first' | 'last'

Name	Type	Description
`type`	`string`	The type of item this node represents.
`key`	`Key`	A unique key for the node.
`value`	`T \| null`	The object value the node was created from.
`level`	`number`	The level of depth this node is at in the hierarchy.
`hasChildNodes`	`boolean`	Whether this item has children, even if not loaded yet.
`rendered`	`ReactNode`	The rendered contents of this node (e.g. JSX).
`textValue`	`string`	A string value for this node, used for features like typeahead.
`index`	`number`	The index of this node within its parent.
`aria-label`	`string`	An accessibility label for this node.
`wrapper`	`( (element: ReactElement )) => ReactElement`	A function that should be called to wrap the rendered node.
`parentKey`	`Key \| null`	The key of the parent node.
`prevKey`	`Key \| null`	The key of the node before this node.
`nextKey`	`Key \| null`	The key of the node after this node.
`props`	`any`	Additional properties specific to a particular node type.
`render`	`( (node: Node<any> )) => ReactElement`	A function that renders this node to a React Element in the DOM.

A generic interface to access a readonly sequential collection of unique keyed items.

Extends: Iterable

Properties

Name	Type	Description
`size`	`number`	The number of items in the collection.

Methods

Method	Description
`getKeys(): Iterable<Key>`	Iterate over all keys in the collection.
`getItem( (key: Key )): T \| null`	Get an item by its key.
`at( (idx: number )): T \| null`	Get an item by the index of its key.
`getKeyBefore( (key: Key )): Key \| null`	Get the key that comes before the given key in the collection.
`getKeyAfter( (key: Key )): Key \| null`	Get the key that comes after the given key in the collection.
`getFirstKey(): Key \| null`	Get the first key in the collection.
`getLastKey(): Key \| null`	Get the last key in the collection.
`getChildren( (key: Key )): Iterable<T>`	Iterate over the child items of the given key.
`getTextValue( (key: Key )): string`	Returns a string representation of the item's contents.

An interface for reading and updating multiple selection state.

Properties

Name	Type	Description
`collection`	`Collection<Node<unknown>>`
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key \| null`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy \| null`	Whether the first or last child of the focused key should receive focus.
`selectedKeys`	`Set<Key>`	The currently selected keys in the collection.
`rawSelection`	`Selection`	The raw selection value for the collection. Either 'all' for select all, or a set of keys.
`isEmpty`	`boolean`	Whether the selection is empty.
`isSelectAll`	`boolean`	Whether all items in the collection are selected.
`firstSelectedKey`	`Key \| null`
`lastSelectedKey`	`Key \| null`
`disabledKeys`	`Set<Key>`
`disabledBehavior`	`DisabledBehavior`

Methods

Method	Description
`constructor( collection: Collection<Node<unknown>>, state: MultipleSelectionState, options?: SelectionManagerOptions ): void`
`setSelectionBehavior( (selectionBehavior: SelectionBehavior )): void`	Sets the selection behavior for the collection.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key \| \| null, , childFocusStrategy?: FocusStrategy )): void`	Sets the focused key.
`isSelected( (key: Key )): void`	Returns whether a key is selected.
`extendSelection( (toKey: Key )): void`	Extends the selection to the given key.
`toggleSelection( (key: Key )): void`	Toggles whether the given key is selected.
`replaceSelection( (key: Key )): void`	Replaces the selection with only the given key.
`setSelectedKeys( (keys: Iterable<Key> )): void`	Replaces the selection with the given keys.
`selectAll(): void`	Selects all items in the collection.
`clearSelection(): void`	Removes all keys from the selection.
`toggleSelectAll(): void`	Toggles between select all and an empty selection.
`select( (key: Key, , e?: PressEvent \| LongPressEvent \| PointerEvent )): void`
`isSelectionEqual( (selection: Set<Key> )): void`	Returns whether the current selection is equal to the given selection.
`canSelectItem( (key: Key )): void`
`isDisabled( (key: Key )): void`
`isLink( (key: Key )): void`
`getItemProps( (key: Key )): void`

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectedKeys`	`Selection`	The currently selected keys in the collection.
`disabledKeys`	`Set<Key>`	The currently disabled keys in the collection.
`disabledBehavior`	`DisabledBehavior`	Whether `disabledKeys` applies to selection, actions, or both.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key \| null`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy \| null`	Whether the first or last child of the focused key should receive focus.

Methods

Method	Description
`setSelectionBehavior( (selectionBehavior: SelectionBehavior )): void`	Sets the selection behavior for the collection.
`setSelectedKeys( (keys: Selection )): void`	Sets the selected keys in the collection.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key \| \| null, , child?: FocusStrategy )): void`	Sets the focused key, and optionally, whether the first or last child of that key should receive focus.

'none'
  | 'single'
  | 'multiple'

'toggle' | 'replace'

'all' | Set<Key>

'selection' | 'all'

Name	Type	Description
`allowsCellSelection`	`boolean`
`layoutDelegate`	`LayoutDelegate`

Properties

Name	Type	Description
`type`	`'pressstart' \| 'pressend' \| 'pressup' \| 'press'`	The type of press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`Element`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.
`x`	`number`	X position relative to the target.
`y`	`number`	Y position relative to the target.

Methods

Method	Description
`continuePropagation(): void`	By default, press events stop propagation to parent elements. In cases where a handler decides not to handle a specific event, it can call `continuePropagation()` to allow a parent to handle it.

'mouse'
  | 'pen'
  | 'touch'
  | 'keyboard'
  | 'virtual'

Name	Type	Description
`type`	`'longpressstart' \| 'longpressend' \| 'longpress'`	The type of long press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`Element`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.
`x`	`number`	X position relative to the target.
`y`	`number`	Y position relative to the target.

Name	Type	Description
`labelProps`	`DOMAttributes`	Props for the label element.
`inputProps`	`InputHTMLAttributes<HTMLInputElement>`	Props for the search input element.
`listBoxProps`	`AriaListBoxOptions<T>`	Props for the list box, to be passed to useListBox.
`clearButtonProps`	`AriaButtonProps`	Props for the search input's clear button.
`descriptionProps`	`DOMAttributes`	Props for the search autocomplete description element, if any.
`errorMessageProps`	`DOMAttributes`	Props for the search autocomplete error message element, if any.
`isInvalid`	`boolean`	Whether the input value is invalid.
`validationErrors`	`string[]`	The current error messages for the input if it is invalid, otherwise an empty array.
`validationDetails`	`ValidityState`	The native validation details for the input.

All DOM attributes supported across both HTML and SVG elements.

Extends: AriaAttributes, ReactDOMAttributes

Name	Type	Description
`id`	`string \| undefined`
`role`	`AriaRole \| undefined`
`tabIndex`	`number \| undefined`
`style`	`CSSProperties \| undefined`
`className`	`string \| undefined`

Name	Type	Default	Description
`isVirtualized`	`boolean`	—	Whether the listbox uses virtual scrolling.
`keyboardDelegate`	`KeyboardDelegate`	—	An optional keyboard delegate implementation for type to select, to override the default.
`layoutDelegate`	`LayoutDelegate`	—	A delegate object that provides layout information for items in the collection. By default this uses the DOM, but this can be overridden to implement things like virtualized scrolling.
`shouldUseVirtualFocus`	`boolean`	—	Whether the listbox items should use virtual focus instead of being focused directly.
`shouldSelectOnPressUp`	`boolean`	—	Whether selection should occur on press up instead of press down.
`shouldFocusOnHover`	`boolean`	—	Whether options should be focused when the user hovers over them.
`linkBehavior`	`'action' \| 'selection' \| 'override'`	`'override'`	The behavior of links in the collection. - 'action': link behaves like onAction. - 'selection': link follows selection interactions (e.g. if URL drives selection). - 'override': links override all other interactions (link items are not selectable).
`label`	`ReactNode`	—	An optional visual label for the listbox.
`selectionBehavior`	`SelectionBehavior`	—	How multiple selection should behave in the collection.
`onAction`	`( (key: Key )) => void`	—	Handler that is called when a user performs an action on an item. The exact user event depends on the collection's `selectionBehavior` prop and the interaction modality.
`autoFocus`	`boolean \| FocusStrategy`	—	Whether to auto focus the listbox or an option.
`shouldFocusWrap`	`boolean`	—	Whether focus should wrap around when the end/start is reached.
`items`	`Iterable<T>`	—	Item objects in the collection.
`disabledKeys`	`Iterable<Key>`	—	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`selectionMode`	`SelectionMode`	—	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	—	Whether the collection allows empty selection.
`selectedKeys`	`'all' \| Iterable<Key>`	—	The currently selected keys in the collection (controlled).
`defaultSelectedKeys`	`'all' \| Iterable<Key>`	—	The initial selected keys in the collection (uncontrolled).
`onSelectionChange`	`( (keys: Selection )) => void`	—	Handler that is called when the selection changes.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.

Name	Type	Default	Description
`isDisabled`	`boolean`	—	Whether the button is disabled.
`children`	`ReactNode`	—	The content to display in the button.
`onPress`	`( (e: PressEvent )) => void`	—	Handler that is called when the press is released over the target.
`onPressStart`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction starts.
`onPressEnd`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
`onPressChange`	`( (isPressed: boolean )) => void`	—	Handler that is called when the press state changes.
`onPressUp`	`( (e: PressEvent )) => void`	—	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`href`	`string`	—	A URL to link to if elementType="a".
`target`	`string`	—	The target window for the link.
`rel`	`string`	—	The relationship between the linked resource and the current page. See MDN.
`elementType`	`ElementType \| JSXElementConstructor<any>`	`'button'`	The HTML element or React element used to render the button, e.g. 'div', 'a', or `RouterLink`.
`aria-expanded`	`boolean \| 'true' \| 'false'`	—	Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
`aria-haspopup`	`boolean \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog' \| 'true' \| 'false'`	—	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
`aria-controls`	`string`	—	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-pressed`	`boolean \| 'true' \| 'false' \| 'mixed'`	—	Indicates the current "pressed" state of toggle buttons.
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	The behavior of the button when used in an HTML form.
`preventFocusOnPress`	`boolean`	—	Whether to prevent focus from moving to the button when pressing it. Caution, this can make the button inaccessible and should only be used when alternative keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's increment/decrement control.
`excludeFromTabOrder`	`boolean`	—	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.

Provides state management for a combo box component. Handles building a collection of items from props and manages the option selection state of the combo box. In addition, it tracks the input value, focus state, and other properties of the combo box.

useComboBoxState<T extends object>(
  (props: ComboBoxStateOptions<T>
)): ComboBoxState<T>

Name	Type	Default	Description
`defaultFilter`	`FilterFn`	—	The filter function used to determine if a option should be included in the combo box list.
`allowsEmptyCollection`	`boolean`	—	Whether the combo box allows the menu to be open when the collection is empty.
`shouldCloseOnBlur`	`boolean`	—	Whether the combo box menu should close on blur.
`defaultItems`	`Iterable<T>`	—	The list of ComboBox items (uncontrolled).
`items`	`Iterable<T>`	—	The list of ComboBox items (controlled).
`onOpenChange`	`( (isOpen: boolean, , menuTrigger?: MenuTriggerAction )) => void`	—	Method that is called when the open state of the menu changes. Returns the new open state and the action that caused the opening of the menu.
`onSelectionChange`	`( (key: Key \| \| null )) => void`	—	Handler that is called when the selection changes.
`inputValue`	`string`	—	The value of the ComboBox input (controlled).
`defaultInputValue`	`string`	—	The default value of the ComboBox input (uncontrolled).
`onInputChange`	`( (value: string )) => void`	—	Handler that is called when the ComboBox input value changes.
`allowsCustomValue`	`boolean`	—	Whether the ComboBox allows a non-item matching input value to be set.
`menuTrigger`	`MenuTriggerAction`	`'input'`	The interaction required to display the ComboBox menu.
`disabledKeys`	`Iterable<Key>`	—	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`selectedKey`	`Key \| null`	—	The currently selected key in the collection (controlled).
`defaultSelectedKey`	`Key`	—	The initial selected key in the collection (uncontrolled).
`isDisabled`	`boolean`	—	Whether the input is disabled.
`isReadOnly`	`boolean`	—	Whether the input can be selected but not changed by the user.
`placeholder`	`string`	—	Temporary text that occupies the text input when it is empty.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission.
`isInvalid`	`boolean`	—	Whether the input value is invalid.
`validationBehavior`	`'aria' \| 'native'`	`'aria'`	Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
`validate`	`( (value: ComboBoxValidationValue )) => ValidationError \| true \| null \| undefined`	—	A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent<HTMLInputElement> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<HTMLInputElement> )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`label`	`ReactNode`	—	The content to display as the label.
`description`	`ReactNode`	—	A description for the field. Provides a hint such as specific requirements for what to choose.
`errorMessage`	`ReactNode \| ( (v: ValidationResult )) => ReactNode`	—	An error message for the field.
`collection`	`Collection<Node<T>>`	—	A pre-constructed collection to use instead of building one from items and children.

(
  (textValue: string,
  , inputValue: string
)) => boolean

Name	Type	Description
`selectedKey`	`Key \| null`	The selected key in the ComboBox.
`inputValue`	`string`	The value of the ComboBox input.

Provides localized string search functionality that is useful for filtering or matching items in a list. Options can be provided to adjust the sensitivity to case, diacritics, and other parameters.

useFilter(
  (options?: Intl.CollatorOptions
)): Filter

Method	Description
`startsWith( (string: string, , substring: string )): boolean`	Returns whether a string starts with a given substring.
`endsWith( (string: string, , substring: string )): boolean`	Returns whether a string ends with a given substring.
`contains( (string: string, , substring: string )): boolean`	Returns whether a string contains a given substring.

useSearchAutocomplete

API#

Features#

Anatomy#

State management#

Example#

Popover#

ListBox#

Usage#

Uncontrolled#

Dynamic collections#

Custom filtering#

Fully controlled#

Menu trigger behavior#

Disabled options#

Asynchronous loading#

Links#

Internationalization#

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods