alpha

useComboBox

Provides the behavior and accessibility implementation for a ComboBox component. A ComboBox combines a text entry with a picker menu, allowing users to filter longer lists to only the selections matching a query.

install	`yarn add @react-aria/combobox`
version	3.0.0-alpha.0
usage	`import {useComboBox} from '@react-aria/combobox'`

View repository

GitHub

View package

NPM

API#

useComboBox<T>(
  (props: AriaComboBoxProps<T>,
  , state: ComboBoxState<T>
)): ComboBoxAria

Features#

There is no native element to implement a ComboBox in HTML. useComboBox helps achieve accessible ComboBox components that can be styled as needed.

Exposed to assistive technology as a ComboBox
Support for selecting a single option
Support for disabled options
Support for sections
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 ComboBox menu using the arrow keys, including automatically focusing the first or last item accordingly
Virtual focus management for ComboBox menu option navigation
VoiceOver announcement enhancements for option focusing, filtering, and selection

Anatomy#

A ComboBox consists of a label, an input which displays the current value, a listbox popup, and a button used to toggle the listbox popup open state. Users can type within the input to filter the available options within the listbox popup. The listbox popup may be opened by a variety of input field interactions specified by the menuTrigger prop provided to useComboBox, or by clicking or touching the ComboBox trigger button. useComboBox handles exposing the correct ARIA attributes for accessibility for each of the components comprising the ComboBox. It should be combined with useListBox, which handles the implementation of the popup listbox, and useButton which handles the button press handlers returned by useComboBox.

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

Name	Type	Description
`buttonProps`	`AriaButtonProps`	Props for the ComboBox menu trigger button.
`inputProps`	`InputHTMLAttributes<HTMLInputElement>`	Props for the ComboBox input element.
`listBoxProps`	`HTMLAttributes<HTMLElement>`	Props for the ComboBox menu.
`labelProps`	`HTMLAttributes<HTMLElement>`	Props for the ComboBox label element.

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

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

State management#

useComboBox requires knowledge of the options in the ComboBox 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 ComboBox is focused, and the current input value. For more information about selection, see Selection.

Usage#

Uncontrolled#

This base example uses an <input> element for the ComboBox text input and a <button> element for the ComboBox menu trigger. A <span> is included within the <button> to display the dropdown arrow icon (hidden from screen readers with aria-hidden). A "contains" filter function is obtained from useFilter and is passed to useComboBoxState so that the ComboBox list can be filtered based on the option text and the current ComboBox input text. The input value, selected option, and menu open state is completely uncontrolled, with the default selected option set by the defaultSelectedKey prop and handled by useComboBoxState.

The listbox popup uses useListBox and useOption to render the list of options. A hidden <DismissButton> is added at the start and end of the popup to allow screen reader users to dismiss the popup. Note that shouldUseVirtualFocus is passed to useListBox and useOption so that browser focus remains within the ComboBox <input> element even when interacting with the ComboBox menu options.

This example does not do any advanced popover positioning or portaling to escape its visual container. See useOverlayTrigger for an example of how to implement this using useOverlayPosition.

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

import {Item} from '@react-stately/collections';
import {mergeProps} from '@react-aria/utils';
import {useButton} from '@react-aria/button';
import {useComboBoxState} from '@react-stately/combobox';
import {useFilter} from '@react-aria/i18n';
import {useListBox, useOption} from '@react-aria/listbox';
import {useOverlay, DismissButton} from '@react-aria/overlays';

function ComboBox(props) {
  // Get a basic "contains" filter function for input value
  // and option text comparison
  let {contains} = useFilter({sensitivity: 'base'});

  // Create state based on the incoming props and the filter function
  let state = useComboBoxState({...props, defaultFilter: contains});

  // Get props for child elements from useComboBox
  let triggerRef = React.useRef();
  let inputRef = React.useRef();
  let listBoxRef = React.useRef();
  let popoverRef = React.useRef();

  let {
    buttonProps: triggerProps,
    inputProps,
    listBoxProps,
    labelProps
  } = useComboBox(
    {
      ...props,
      inputRef,
      buttonRef: triggerRef,
      listBoxRef,
      popoverRef,
      menuTrigger: 'input'
    },
    state
  );

  // Get props for the ComboBox trigger button based on the button
  // props from useComboBox
  let {buttonProps} = useButton(triggerProps, triggerRef);

  return (
    <div style={{position: 'relative', display: 'inline-block'}}>
      <div {...labelProps}>{props.label}</div>
      <input
        {...inputProps}
        ref={inputRef}
        style={{
          borderRight: 0,
          borderBottomRightRadius: 0,
          borderTopRightRadius: 0
        }}
      />
      <button
        {...buttonProps}
        ref={triggerRef}
        style={{
          height: '21px',
          borderBottomLeftRadius: 0,
          borderTopLeftRadius: 0
        }}>
        <span aria-hidden="true" style={{paddingLeft: 5}}>
          ▼
        </span>
      </button>
      {state.isOpen && (
        <ListBoxPopup
          {...listBoxProps}
          // Use virtual focus to get aria-activedescendant tracking and
          // ensure focus doesn't leave the input field
          shouldUseVirtualFocus
          listBoxRef={listBoxRef}
          popoverRef={popoverRef}
          state={state}
        />
      )}
    </div>
  );
}

function ListBoxPopup(props) {
  let {
    popoverRef,
    listBoxRef,
    state,
    shouldUseVirtualFocus,
    ...otherProps
  } = props;

  // Get props for the listbox.
  // Prevent focus moving to listbox via shouldUseVirtualFocus
  let {listBoxProps} = useListBox(
    {
      autoFocus: state.focusStrategy,
      disallowEmptySelection: true,
      shouldUseVirtualFocus,
      ...otherProps
    },
    state,
    listBoxRef
  );

  // Handle events that should cause the popup to close,
  // e.g. blur, clicking outside, or pressing the escape key.
  let {overlayProps} = useOverlay(
    {
      onClose: () => state.close(),
      shouldCloseOnBlur: true,
      isOpen: state.isOpen,
      isDismissable: true
    },
    popoverRef
  );

  // Add hidden <DismissButton> components at the start and end of the list
  // to allow screen reader users to dismiss the popup easily.
  return (
    <div {...overlayProps} ref={popoverRef}>
      <DismissButton onDismiss={() => state.close()} />
      <ul
        {...mergeProps(listBoxProps, otherProps)}
        ref={listBoxRef}
        style={{
          position: 'absolute',
          width: '100%',
          margin: '4px 0 0 0',
          padding: 0,
          listStyle: 'none',
          border: '1px solid gray',
          background: 'lightgray'
        }}>
        {[...state.collection].map((item) => (
          <Option
            shouldUseVirtualFocus
            key={item.key}
            item={item}
            state={state}
          />
        ))}
      </ul>
      <DismissButton onDismiss={() => state.close()} />
    </div>
  );
}

function Option({item, state, shouldUseVirtualFocus}) {
  let ref = React.useRef();
  let isDisabled = state.disabledKeys.has(item.key);
  let isSelected = state.selectionManager.isSelected(item.key);
  // Track focus via focusedKey state instead of with focus event listeners
  // since focus never leaves the text input in a ComboBox
  let isFocused = state.selectionManager.focusedKey === item.key;

  // Get props for the option element.
  // Prevent options from receiving browser focus via shouldUseVirtualFocus.
  let {optionProps} = useOption(
    {
      key: item.key,
      isDisabled,
      isSelected,
      shouldSelectOnPressUp: true,
      shouldFocusOnHover: true,
      shouldUseVirtualFocus
    },
    state,
    ref
  );

  let backgroundColor;
  let color;

  if (isSelected) {
    backgroundColor = 'blueviolet';
    color = 'white';
  } else if (isFocused) {
    backgroundColor = 'gray';
    color = 'black';
  } 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>
  );
}

<ComboBox label="Favorite Animal" defaultSelectedKey="red panda">
  <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>
</ComboBox>

import {Item} from '@react-stately/collections';
import {mergeProps} from '@react-aria/utils';
import {useButton} from '@react-aria/button';
import {useComboBoxState} from '@react-stately/combobox';
import {useFilter} from '@react-aria/i18n';
import {useListBox, useOption} from '@react-aria/listbox';
import {
  useOverlay,
  DismissButton
} from '@react-aria/overlays';

function ComboBox(props) {
  // Get a basic "contains" filter function for input value
  // and option text comparison
  let {contains} = useFilter({sensitivity: 'base'});

  // Create state based on the incoming props and the filter function
  let state = useComboBoxState({
    ...props,
    defaultFilter: contains
  });

  // Get props for child elements from useComboBox
  let triggerRef = React.useRef();
  let inputRef = React.useRef();
  let listBoxRef = React.useRef();
  let popoverRef = React.useRef();

  let {
    buttonProps: triggerProps,
    inputProps,
    listBoxProps,
    labelProps
  } = useComboBox(
    {
      ...props,
      inputRef,
      buttonRef: triggerRef,
      listBoxRef,
      popoverRef,
      menuTrigger: 'input'
    },
    state
  );

  // Get props for the ComboBox trigger button based on the button
  // props from useComboBox
  let {buttonProps} = useButton(triggerProps, triggerRef);

  return (
    <div
      style={{
        position: 'relative',
        display: 'inline-block'
      }}>
      <div {...labelProps}>{props.label}</div>
      <input
        {...inputProps}
        ref={inputRef}
        style={{
          borderRight: 0,
          borderBottomRightRadius: 0,
          borderTopRightRadius: 0
        }}
      />
      <button
        {...buttonProps}
        ref={triggerRef}
        style={{
          height: '21px',
          borderBottomLeftRadius: 0,
          borderTopLeftRadius: 0
        }}>
        <span aria-hidden="true" style={{paddingLeft: 5}}>
          ▼
        </span>
      </button>
      {state.isOpen && (
        <ListBoxPopup
          {...listBoxProps}
          // Use virtual focus to get aria-activedescendant tracking and
          // ensure focus doesn't leave the input field
          shouldUseVirtualFocus
          listBoxRef={listBoxRef}
          popoverRef={popoverRef}
          state={state}
        />
      )}
    </div>
  );
}

function ListBoxPopup(props) {
  let {
    popoverRef,
    listBoxRef,
    state,
    shouldUseVirtualFocus,
    ...otherProps
  } = props;

  // Get props for the listbox.
  // Prevent focus moving to listbox via shouldUseVirtualFocus
  let {listBoxProps} = useListBox(
    {
      autoFocus: state.focusStrategy,
      disallowEmptySelection: true,
      shouldUseVirtualFocus,
      ...otherProps
    },
    state,
    listBoxRef
  );

  // Handle events that should cause the popup to close,
  // e.g. blur, clicking outside, or pressing the escape key.
  let {overlayProps} = useOverlay(
    {
      onClose: () => state.close(),
      shouldCloseOnBlur: true,
      isOpen: state.isOpen,
      isDismissable: true
    },
    popoverRef
  );

  // Add hidden <DismissButton> components at the start and end of the list
  // to allow screen reader users to dismiss the popup easily.
  return (
    <div {...overlayProps} ref={popoverRef}>
      <DismissButton onDismiss={() => state.close()} />
      <ul
        {...mergeProps(listBoxProps, otherProps)}
        ref={listBoxRef}
        style={{
          position: 'absolute',
          width: '100%',
          margin: '4px 0 0 0',
          padding: 0,
          listStyle: 'none',
          border: '1px solid gray',
          background: 'lightgray'
        }}>
        {[...state.collection].map((item) => (
          <Option
            shouldUseVirtualFocus
            key={item.key}
            item={item}
            state={state}
          />
        ))}
      </ul>
      <DismissButton onDismiss={() => state.close()} />
    </div>
  );
}

function Option({item, state, shouldUseVirtualFocus}) {
  let ref = React.useRef();
  let isDisabled = state.disabledKeys.has(item.key);
  let isSelected = state.selectionManager.isSelected(
    item.key
  );
  // Track focus via focusedKey state instead of with focus event listeners
  // since focus never leaves the text input in a ComboBox
  let isFocused =
    state.selectionManager.focusedKey === item.key;

  // Get props for the option element.
  // Prevent options from receiving browser focus via shouldUseVirtualFocus.
  let {optionProps} = useOption(
    {
      key: item.key,
      isDisabled,
      isSelected,
      shouldSelectOnPressUp: true,
      shouldFocusOnHover: true,
      shouldUseVirtualFocus
    },
    state,
    ref
  );

  let backgroundColor;
  let color;

  if (isSelected) {
    backgroundColor = 'blueviolet';
    color = 'white';
  } else if (isFocused) {
    backgroundColor = 'gray';
    color = 'black';
  } 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>
  );
}

<ComboBox
  label="Favorite Animal"
  defaultSelectedKey="red panda">
  <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>
</ComboBox>

import {Item} from '@react-stately/collections';
import {mergeProps} from '@react-aria/utils';
import {useButton} from '@react-aria/button';
import {useComboBoxState} from '@react-stately/combobox';
import {useFilter} from '@react-aria/i18n';
import {
  useListBox,
  useOption
} from '@react-aria/listbox';
import {
  useOverlay,
  DismissButton
} from '@react-aria/overlays';

function ComboBox(
  props
) {
  // Get a basic "contains" filter function for input value
  // and option text comparison
  let {
    contains
  } = useFilter({
    sensitivity: 'base'
  });

  // Create state based on the incoming props and the filter function
  let state = useComboBoxState(
    {
      ...props,
      defaultFilter: contains
    }
  );

  // Get props for child elements from useComboBox
  let triggerRef = React.useRef();
  let inputRef = React.useRef();
  let listBoxRef = React.useRef();
  let popoverRef = React.useRef();

  let {
    buttonProps: triggerProps,
    inputProps,
    listBoxProps,
    labelProps
  } = useComboBox(
    {
      ...props,
      inputRef,
      buttonRef: triggerRef,
      listBoxRef,
      popoverRef,
      menuTrigger:
        'input'
    },
    state
  );

  // Get props for the ComboBox trigger button based on the button
  // props from useComboBox
  let {
    buttonProps
  } = useButton(
    triggerProps,
    triggerRef
  );

  return (
    <div
      style={{
        position:
          'relative',
        display:
          'inline-block'
      }}>
      <div
        {...labelProps}>
        {props.label}
      </div>
      <input
        {...inputProps}
        ref={inputRef}
        style={{
          borderRight: 0,
          borderBottomRightRadius: 0,
          borderTopRightRadius: 0
        }}
      />
      <button
        {...buttonProps}
        ref={triggerRef}
        style={{
          height: '21px',
          borderBottomLeftRadius: 0,
          borderTopLeftRadius: 0
        }}>
        <span
          aria-hidden="true"
          style={{
            paddingLeft: 5
          }}>
          ▼
        </span>
      </button>
      {state.isOpen && (
        <ListBoxPopup
          {...listBoxProps}
          // Use virtual focus to get aria-activedescendant tracking and
          // ensure focus doesn't leave the input field
          shouldUseVirtualFocus
          listBoxRef={
            listBoxRef
          }
          popoverRef={
            popoverRef
          }
          state={state}
        />
      )}
    </div>
  );
}

function ListBoxPopup(
  props
) {
  let {
    popoverRef,
    listBoxRef,
    state,
    shouldUseVirtualFocus,
    ...otherProps
  } = props;

  // Get props for the listbox.
  // Prevent focus moving to listbox via shouldUseVirtualFocus
  let {
    listBoxProps
  } = useListBox(
    {
      autoFocus:
        state.focusStrategy,
      disallowEmptySelection: true,
      shouldUseVirtualFocus,
      ...otherProps
    },
    state,
    listBoxRef
  );

  // Handle events that should cause the popup to close,
  // e.g. blur, clicking outside, or pressing the escape key.
  let {
    overlayProps
  } = useOverlay(
    {
      onClose: () =>
        state.close(),
      shouldCloseOnBlur: true,
      isOpen:
        state.isOpen,
      isDismissable: true
    },
    popoverRef
  );

  // Add hidden <DismissButton> components at the start and end of the list
  // to allow screen reader users to dismiss the popup easily.
  return (
    <div
      {...overlayProps}
      ref={popoverRef}>
      <DismissButton
        onDismiss={() =>
          state.close()
        }
      />
      <ul
        {...mergeProps(
          listBoxProps,
          otherProps
        )}
        ref={listBoxRef}
        style={{
          position:
            'absolute',
          width: '100%',
          margin:
            '4px 0 0 0',
          padding: 0,
          listStyle:
            'none',
          border:
            '1px solid gray',
          background:
            'lightgray'
        }}>
        {[
          ...state.collection
        ].map((item) => (
          <Option
            shouldUseVirtualFocus
            key={
              item.key
            }
            item={item}
            state={state}
          />
        ))}
      </ul>
      <DismissButton
        onDismiss={() =>
          state.close()
        }
      />
    </div>
  );
}

function Option({
  item,
  state,
  shouldUseVirtualFocus
}) {
  let ref = React.useRef();
  let isDisabled = state.disabledKeys.has(
    item.key
  );
  let isSelected = state.selectionManager.isSelected(
    item.key
  );
  // Track focus via focusedKey state instead of with focus event listeners
  // since focus never leaves the text input in a ComboBox
  let isFocused =
    state
      .selectionManager
      .focusedKey ===
    item.key;

  // Get props for the option element.
  // Prevent options from receiving browser focus via shouldUseVirtualFocus.
  let {
    optionProps
  } = useOption(
    {
      key: item.key,
      isDisabled,
      isSelected,
      shouldSelectOnPressUp: true,
      shouldFocusOnHover: true,
      shouldUseVirtualFocus
    },
    state,
    ref
  );

  let backgroundColor;
  let color;

  if (isSelected) {
    backgroundColor =
      'blueviolet';
    color = 'white';
  } else if (isFocused) {
    backgroundColor =
      'gray';
    color = 'black';
  } 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>
  );
}

<ComboBox
  label="Favorite Animal"
  defaultSelectedKey="red panda">
  <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>
</ComboBox>

Controlled#

The following example shows how you would create a controlled ComboBox, controlling everything from the selected value (selectedKey) to the combobox options (items). By passing in inputValue, selectedKey, isOpen, and items to the useComboBoxState hook you can control what exactly your ComboBox should display.

It is important to note that you don't have to control every single aspect of a ComboBox. If you decide to only control a single property of the ComboBox, be sure to provide the change handler for that prop as well e.g. controlling selectedKey would require onSelectionChange to be passed to useComboBox as well.

// Using the same ComboBox component code from the previous example...

function ControlledComboBox() {
  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 ComboBox input value, selected option, and open state
  // in a state tracker
  let [fieldState, setFieldState] = React.useState({
    isOpen: false,
    selectedKey: '',
    inputValue: ''
  });

  // Implement custom filtering logic and control what items are
  // available to the ComboBox.
  // Memoize filteredItems so it updates when the inputValue updates.
  let {startsWith} = useFilter({sensitivity: 'base'});
  let filteredItems = React.useMemo(
    () =>
      optionList.filter((item) => startsWith(item.name, fieldState.inputValue)),
    [optionList, fieldState.inputValue]
  );

  // Specify how each of the ComboBox values should change when an
  // option is selected from the menu
  let onSelectionChange = (key) => {
    setFieldState({
      isOpen: false,
      inputValue: filteredItems.find((option) => option.id === key)?.name ?? '',
      selectedKey: key
    });
  };

  // Specify how each of the ComboBox values should change when the input
  // field is altered by the end user
  let onInputChange = (value) => {
    setFieldState((prevState) => ({
      isOpen: true,
      inputValue: value,
      selectedKey: value === '' ? null : prevState.selectedKey
    }));
  };

  // Specify how each of the ComboBox values should change when the menu's
  // open state is changed
  let onOpenChange = (isOpen) => {
    setFieldState((prevState) => ({
      isOpen,
      inputValue: prevState.inputValue,
      selectedKey: prevState.selectedKey
    }));
  };

  // Pass each controlled prop to useComboBox along with their
  // change handlers
  return (
    <ComboBox
      label="Favorite Animal"
      items={filteredItems}
      selectedKey={fieldState.selectedKey}
      inputValue={fieldState.inputValue}
      isOpen={fieldState.isOpen}
      onOpenChange={onOpenChange}
      onSelectionChange={onSelectionChange}
      onInputChange={onInputChange}>
      {(item) => <Item>{item.name}</Item>}
    </ComboBox>
  );
}

<ControlledComboBox />

// Using the same ComboBox component code from the previous example...

function ControlledComboBox() {
  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 ComboBox input value, selected option, and open state
  // in a state tracker
  let [fieldState, setFieldState] = React.useState({
    isOpen: false,
    selectedKey: '',
    inputValue: ''
  });

  // Implement custom filtering logic and control what items are
  // available to the ComboBox.
  // Memoize filteredItems so it updates when the inputValue updates.
  let {startsWith} = useFilter({sensitivity: 'base'});
  let filteredItems = React.useMemo(
    () =>
      optionList.filter((item) =>
        startsWith(item.name, fieldState.inputValue)
      ),
    [optionList, fieldState.inputValue]
  );

  // Specify how each of the ComboBox values should change when an
  // option is selected from the menu
  let onSelectionChange = (key) => {
    setFieldState({
      isOpen: false,
      inputValue:
        filteredItems.find((option) => option.id === key)
          ?.name ?? '',
      selectedKey: key
    });
  };

  // Specify how each of the ComboBox values should change when the input
  // field is altered by the end user
  let onInputChange = (value) => {
    setFieldState((prevState) => ({
      isOpen: true,
      inputValue: value,
      selectedKey:
        value === '' ? null : prevState.selectedKey
    }));
  };

  // Specify how each of the ComboBox values should change when the menu's
  // open state is changed
  let onOpenChange = (isOpen) => {
    setFieldState((prevState) => ({
      isOpen,
      inputValue: prevState.inputValue,
      selectedKey: prevState.selectedKey
    }));
  };

  // Pass each controlled prop to useComboBox along with their
  // change handlers
  return (
    <ComboBox
      label="Favorite Animal"
      items={filteredItems}
      selectedKey={fieldState.selectedKey}
      inputValue={fieldState.inputValue}
      isOpen={fieldState.isOpen}
      onOpenChange={onOpenChange}
      onSelectionChange={onSelectionChange}
      onInputChange={onInputChange}>
      {(item) => <Item>{item.name}</Item>}
    </ComboBox>
  );
}

<ControlledComboBox />

// Using the same ComboBox component code from the previous example...

function ControlledComboBox() {
  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 ComboBox input value, selected option, and open state
  // in a state tracker
  let [
    fieldState,
    setFieldState
  ] = React.useState({
    isOpen: false,
    selectedKey: '',
    inputValue: ''
  });

  // Implement custom filtering logic and control what items are
  // available to the ComboBox.
  // Memoize filteredItems so it updates when the inputValue updates.
  let {
    startsWith
  } = useFilter({
    sensitivity: 'base'
  });
  let filteredItems = React.useMemo(
    () =>
      optionList.filter(
        (item) =>
          startsWith(
            item.name,
            fieldState.inputValue
          )
      ),
    [
      optionList,
      fieldState.inputValue
    ]
  );

  // Specify how each of the ComboBox values should change when an
  // option is selected from the menu
  let onSelectionChange = (
    key
  ) => {
    setFieldState({
      isOpen: false,
      inputValue:
        filteredItems.find(
          (option) =>
            option.id ===
            key
        )?.name ?? '',
      selectedKey: key
    });
  };

  // Specify how each of the ComboBox values should change when the input
  // field is altered by the end user
  let onInputChange = (
    value
  ) => {
    setFieldState(
      (prevState) => ({
        isOpen: true,
        inputValue: value,
        selectedKey:
          value === ''
            ? null
            : prevState.selectedKey
      })
    );
  };

  // Specify how each of the ComboBox values should change when the menu's
  // open state is changed
  let onOpenChange = (
    isOpen
  ) => {
    setFieldState(
      (prevState) => ({
        isOpen,
        inputValue:
          prevState.inputValue,
        selectedKey:
          prevState.selectedKey
      })
    );
  };

  // Pass each controlled prop to useComboBox along with their
  // change handlers
  return (
    <ComboBox
      label="Favorite Animal"
      items={
        filteredItems
      }
      selectedKey={
        fieldState.selectedKey
      }
      inputValue={
        fieldState.inputValue
      }
      isOpen={
        fieldState.isOpen
      }
      onOpenChange={
        onOpenChange
      }
      onSelectionChange={
        onSelectionChange
      }
      onInputChange={
        onInputChange
      }>
      {(item) => (
        <Item>
          {item.name}
        </Item>
      )}
    </ComboBox>
  );
}

<ControlledComboBox />

Allow custom values#

By default, useComboBoxState doesn't allow users to specify a value that doesn't exist in the list of options and will revert the input value to the current selected value on blur. By specifying allowsCustomValue, this behavior is suppressed and the user is free to enter any value within the field.

// Using the same ComboBox component code from the first example...

<ComboBox label="Favorite Animal" allowsCustomValue>
  <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>
</ComboBox>

// Using the same ComboBox component code from the first example...

<ComboBox label="Favorite Animal" allowsCustomValue>
  <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>
</ComboBox>

// Using the same ComboBox component code from the first example...

<ComboBox
  label="Favorite Animal"
  allowsCustomValue>
  <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>
</ComboBox>

useComboBoxState supports three different menuTrigger prop values:

input (default): ComboBox menu opens when the user edits the input text.
focus: ComboBox menu opens when the user focuses the ComboBox input.
manual: ComboBox menu only opens when the user presses the trigger button.

The example below has menuTrigger set to focus.

// Using the same ComboBox component code from the first example...

<ComboBox label="Favorite Animal" 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>
</ComboBox>

// Using the same ComboBox component code from the first example...

<ComboBox label="Favorite Animal" 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>
</ComboBox>

// Using the same ComboBox component code from the first example...

<ComboBox
  label="Favorite Animal"
  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>
</ComboBox>

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.

// Using the same ComboBox component code from the first example...

<ComboBox label="Favorite Animal" 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>
</ComboBox>

// Using the same ComboBox component code from the first example...

<ComboBox
  label="Favorite Animal"
  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>
</ComboBox>

// Using the same ComboBox component code from the first example...

<ComboBox
  label="Favorite Animal"
  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>
</ComboBox>

Internationalization#

useComboBox handles some aspects of internationalization automatically. For example, the item focus, count, and selection VoiceOver announcements are formatted to match the current locale. You are responsible for localizing all labels and option content that is passed into the select.

RTL#

In right-to-left languages, the ComboBox should be mirrored. The trigger button should be on the left, and the input element should be on the right. In addition, the content of ComboBox options should flip. Ensure that your CSS accounts for this.

Name	Type	Default	Description
`buttonRef`	`RefObject<HTMLElement>`	—	The ref for the ComboBox menu trigger button.
`inputRef`	`RefObject<HTMLInputElement \| HTMLTextAreaElement>`	—	The ref for the ComboBox input element.
`popoverRef`	`RefObject<HTMLDivElement>`	—	The ref for the ComboBox menu popover.
`listBoxRef`	`RefObject<HTMLElement>`	—	The ref for the ComboBox menu.
`children`	`CollectionChildren<T>`	—	The contents of the collection.
`keyboardDelegate`	`KeyboardDelegate`	—	An optional keyboard delegate implementation for ComboBox, to override the default.
`defaultItems`	`Iterable<T>`	—	The list of ComboBox items (uncontrolled).
`items`	`Iterable<T>`	—	The list of ComboBox items (controlled).
`isOpen`	`boolean`	—	Sets the open state of the menu.
`defaultOpen`	`boolean`	—	Sets the default open state of the menu.
`onOpenChange`	`( (isOpen: boolean )) => void`	—	Method that is called when the open state of the menu 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`	`'focus' \| 'input' \| 'manual'`	`'input'`	The interaction required to display the ComboBox menu.
`shouldFlip`	`boolean`	`true`	Whether the menu should automatically flip direction when space is limited.
`disabledKeys`	`Iterable<Key>`	—	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`disallowEmptySelection`	`boolean`	—	Whether the collection allows empty selection.
`selectedKey`	`Key`	—	The currently selected key in the collection (controlled).
`defaultSelectedKey`	`Key`	—	The initial selected key in the collection (uncontrolled).
`onSelectionChange`	`( (key: Key )) => any`	—	Handler that is called when the selection changes.
`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.
`id`	`string`	—	The element's unique identifier. See MDN.
`validationState`	`ValidationState`	—	Whether the input should display its "valid" or "invalid" visual styling.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission. Often paired with the `necessityIndicator` prop to add a visual indicator to the input.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent )) => 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.

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

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

SectionElement<T> | ItemElement<T>

ReactElement<SectionProps<T>>

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

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.

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

'valid' | 'invalid'

BaseEvent<ReactKeyboardEvent<any>>

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

Properties

Name	Type	Description
`inputValue`	`string`	The current value of the ComboBox input.
`isFocused`	`boolean`	Whether the select is currently focused.
`selectedKey`	`Key`	The key for the currently selected item.
`selectedItem`	`Node<T>`	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.
`focusStrategy`	`FocusStrategy`	Controls which item will be auto focused when the menu opens.
`isOpen`	`boolean`	Whether the overlay is currently open.

Methods

Method	Description
`setInputValue( (value: string )): void`	Sets the value of the ComboBox input.
`commit(): void`	Function that when called handles updating the ComboBox's input value and selected key.
`setFocused( (isFocused: boolean )): void`	Sets whether the select is focused.
`setSelectedKey( (key: Key )): void`	Sets the selected key.
`open( (focusStrategy: FocusStrategy \| \| null )): void`	Opens the menu.
`toggle( (focusStrategy: FocusStrategy \| \| null )): void`	Toggles the menu.
`close(): void`	Closes the overlay.

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

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

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`	Get an item by 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.

An interface for reading and updating multiple selection state.

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.
`selectedKeys`	`Set<Key>`	The currently selected keys in the collection.
`isEmpty`	`boolean`	Whether the selection is empty.
`isSelectAll`	`boolean`	Whether all items in the collection are selected.
`firstSelectedKey`	`Key \| null`
`lastSelectedKey`	`Key \| null`

Methods

Method	Description
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key )): 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.
`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 \| \| PointerEvent )): void`

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in 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.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.

Methods

Method	Description
`setSelectedKeys( (keys: Selection \| \| ( (v: Selection )) => Selection )): void`	Sets the selected keys in the collection.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key )): void`	Sets the focused key.

'none'
  | 'single'
  | 'multiple'

'all' | Set<Key>

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`	`HTMLElement`	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.

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

'first' | 'last'

Name	Type	Description
`buttonProps`	`AriaButtonProps`	Props for the ComboBox menu trigger button.
`inputProps`	`InputHTMLAttributes<HTMLInputElement>`	Props for the ComboBox input element.
`listBoxProps`	`HTMLAttributes<HTMLElement>`	Props for the ComboBox menu.
`labelProps`	`HTMLAttributes<HTMLElement>`	Props for the ComboBox label element.

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 )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent )) => 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`	`T \| JSXElementConstructor<any>`	`'button'`	The HTML element or React element used to render the button, e.g. 'div', 'a', or `RouterLink`.
`aria-expanded`	`boolean`	—	Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
`aria-haspopup`	`boolean \| '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-controls`	`string`	—	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-pressed`	`boolean`	—	Indicates the current "pressed" state of toggle buttons.
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	The behavior of the button when used in an HTML form.
`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 ComboBox component. Handles building a collection of items from props and manages the option selection state of the ComboBox. Also tracks the input value, focus state, and other properties of the ComboBox.

useComboBoxState<T>(
  (props: ComboBoxStateProps<T>
)): ComboBoxState<T>

Name	Type	Default	Description
`children`	`CollectionChildren<T>`	—	The contents of the collection.
`defaultFilter`	`FilterFn`	—	The filter function used to determine if a option should be included in the ComboBox list.
`allowsEmptyCollection`	`boolean`	—	Whether the ComboBox allows the menu to be open when the collection is empty.
`shouldCloseOnBlur`	`boolean`	—	Whether the ComboBox menu should close on blur.
`defaultItems`	`Iterable<T>`	—	The list of ComboBox items (uncontrolled).
`items`	`Iterable<T>`	—	The list of ComboBox items (controlled).
`isOpen`	`boolean`	—	Sets the open state of the menu.
`defaultOpen`	`boolean`	—	Sets the default open state of the menu.
`onOpenChange`	`( (isOpen: boolean )) => void`	—	Method that is called when the open state of the menu 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`	`'focus' \| 'input' \| 'manual'`	`'input'`	The interaction required to display the ComboBox menu.
`shouldFlip`	`boolean`	`true`	Whether the menu should automatically flip direction when space is limited.
`disabledKeys`	`Iterable<Key>`	—	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`disallowEmptySelection`	`boolean`	—	Whether the collection allows empty selection.
`selectedKey`	`Key`	—	The currently selected key in the collection (controlled).
`defaultSelectedKey`	`Key`	—	The initial selected key in the collection (uncontrolled).
`onSelectionChange`	`( (key: Key )) => any`	—	Handler that is called when the selection changes.
`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.
`id`	`string`	—	The element's unique identifier. See MDN.
`validationState`	`ValidationState`	—	Whether the input should display its "valid" or "invalid" visual styling.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission. Often paired with the `necessityIndicator` prop to add a visual indicator to the input.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent )) => 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.

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

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.

Provides the behavior and accessibility implementation for a listbox component. A listbox displays a list of options and allows a user to select one or more of them.

useListBox<T>(
  props: AriaListBoxOptions<T>,
  state: ListState<T>,
  ref: RefObject<HTMLElement>
): ListBoxAria

Name	Type	Description
`isVirtualized`	`boolean`	Whether the listbox uses virtual scrolling.
`keyboardDelegate`	`KeyboardDelegate`	An optional keyboard delegate implementation for type to select, to override the default.
`label`	`ReactNode`	An optional visual label for the listbox.
`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.
`isLoading`	`boolean`	Whether the items are currently loading.
`onLoadMore`	`() => any`	Handler that is called when more items should be loaded, e.g. while scrolling near the bottom.
`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 )) => any`	Handler that is called when the selection 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	Description
`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.

Name	Type	Description
`listBoxProps`	`HTMLAttributes<HTMLElement>`	Props for the listbox element.
`labelProps`	`HTMLAttributes<HTMLElement>`	Props for the listbox's visual label element (if any).

Provides the behavior and accessibility implementation for an option in a listbox. See useListBox for more details about listboxes.

useOption<T>(
  props: AriaOptionProps,
  state: ListState<T>,
  ref: RefObject<HTMLElement>
): OptionAria

Name	Type	Description
`isDisabled`	`boolean`	Whether the option is disabled.
`isSelected`	`boolean`	Whether the option is selected.
`aria-label`	`string`	A screen reader only label for the option.
`key`	`Key`	The unique key for the option.
`shouldSelectOnPressUp`	`boolean`	Whether selection should occur on press up instead of press down.
`shouldFocusOnHover`	`boolean`	Whether the option should be focused when the user hovers over it.
`isVirtualized`	`boolean`	Whether the option is contained in a virtual scrolling listbox.
`shouldUseVirtualFocus`	`boolean`	Whether the option should use virtual focus instead of being focused directly.

Name	Type	Description
`optionProps`	`HTMLAttributes<HTMLElement>`	Props for the option element.
`labelProps`	`HTMLAttributes<HTMLElement>`	Props for the main text element inside the option.
`descriptionProps`	`HTMLAttributes<HTMLElement>`	Props for the description text element inside the option, if any.

A visually hidden button that can be used to allow screen reader users to dismiss a modal or popup when there is no visual affordance to do so.

Name	Type	Description
`onDismiss`	`() => void`	Called when the dismiss button is activated.

Handles positioning overlays like popovers and menus relative to a trigger element, and updating the position when the window resizes.

useOverlayPosition(
  (props: AriaPositionProps
)): PositionAria

Name	Type	Default	Description
`targetRef`	`RefObject<HTMLElement>`	—	The ref for the element which the overlay positions itself with respect to.
`overlayRef`	`RefObject<HTMLElement>`	—	The ref for the overlay element.
`boundaryElement`	`HTMLElement`	`document.body`	Element that that serves as the positioning boundary.
`scrollRef`	`RefObject<HTMLElement>`	`overlayRef`	A ref for the scrollable region within the overlay.
`shouldUpdatePosition`	`boolean`	`true`	Whether the overlay should update its position automatically.
`onClose`	`() => void`	—	Handler that is called when the overlay should close.
`placement`	`Placement`	`'bottom'`	The placement of the element with respect to its anchor element.
`containerPadding`	`number`	`12`	The placement padding that should be applied between the element and its surrounding container.
`offset`	`number`	`0`	The additional offset applied along the main axis between the element and its anchor element.
`crossOffset`	`number`	`0`	The additional offset applied along the cross axis between the element and its anchor element.
`shouldFlip`	`boolean`	`true`	Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.
`isOpen`	`boolean`	—	Whether the element is rendered.

'bottom'
  | 'bottom left'
  | 'bottom right'
  | 'bottom start'
  | 'bottom end'
  | 'top'
  | 'top left'
  | 'top right'
  | 'top start'
  | 'top end'
  | 'left'
  | 'left top'
  | 'left bottom'
  | 'start'
  | 'start top'
  | 'start bottom'
  | 'right'
  | 'right top'
  | 'right bottom'
  | 'end'
  | 'end top'
  | 'end bottom'

Properties

Name	Type	Description
`overlayProps`	`HTMLAttributes<Element>`	Props for the overlay container element.
`arrowProps`	`HTMLAttributes<Element>`	Props for the overlay tip arrow if any.
`placement`	`PlacementAxis`	Placement of the overlay with respect to the overlay trigger.

Methods

Method	Description
`updatePosition(): void`	Updates the position of the overlay.

Axis | 'center'

'top'
  | 'bottom'
  | 'left'
  | 'right'

useComboBox

API#

Features#

Anatomy#

State management#

Usage#

Uncontrolled#

Controlled#

Allow custom values#

Menu trigger behavior#

Disabled options#

Internationalization#

RTL#

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods