useMenuTrigger

Provides the behavior and accessibility implementation for a menu trigger.

install	`yarn add @react-aria/menu`
version	3.0.0-alpha.1
usage	`import {useMenuTrigger} from '@react-aria/menu'`

View ARIA spec

W3C

API#

useMenuTrigger(
  props: MenuTriggerAriaProps,
  state: MenuTriggerState,
  ref: RefObject<HTMLElement>
): MenuTriggerAria

Features#

There is no native element to implement a menu in HTML that is widely supported. useMenuTrigger combined with useMenu helps achieve accessible menu components that can be styled as needed.

Exposed to assistive technology as a button with a menu popup using ARIA (combined with useMenu)
Support for mouse, touch, and keyboard interactions
Keyboard support for opening the menu using the arrow keys, including automatically focusing the first or last item accordingly

Anatomy#

A menu trigger consists of a button or other trigger element combined with a popup menu. It should be combined with useButton and useMenu, which handle the implementation of the button and popup menu respectively.

useMenuTrigger returns props that you should spread onto the appropriate element:

Name	Type	Description
`menuTriggerProps`	`AriaButtonProps`	Props for the menu trigger element.
`menuProps`	`HTMLAttributes<HTMLElement>`	Props for the menu.

State is managed by the useMenuTriggerState hook from @react-stately/menu. The state object should be passed as an option to useMenuTrigger

Example#

This example shows how to build a menu button using useMenuTrigger, useButton, and useMenu.

The menu popup uses useMenu and useMenuItem to render the menu and its items. In addition, a <FocusScope> is used to automatically restore focus to the trigger when the menu closes. A hidden <DismissButton> is added at the start and end of the menu to allow screen reader users to dismiss it easily.

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 useMenu for examples of menu item groups, and more complex item content.

import {useMenuTriggerState} from '@react-stately/menu';
import {useButton} from '@react-aria/button';
import {useMenu, useMenuItem} from '@react-aria/menu';
import {useTreeState} from '@react-stately/tree';
import {Item} from '@react-stately/collections';
import {mergeProps} from '@react-aria/utils';
import {FocusScope} from '@react-aria/focus';
import {useFocus} from '@react-aria/interactions';
import {useOverlay, DismissButton} from '@react-aria/overlays';

function MenuButton(props) {
  // Create state based on the incoming props
  let state = useMenuTriggerState(props);

  // Get props for the menu trigger and menu elements
  let ref = React.useRef();
  let {menuTriggerProps, menuProps} = useMenuTrigger({}, state, ref);

  // Get props for the button based on the trigger props from useMenuTrigger
  let {buttonProps} = useButton(menuTriggerProps, ref);

  return (
    <div style={{position: 'relative', display: 'inline-block'}}>
      <button
        {...buttonProps}
        ref={ref}
        style={{height: 30, fontSize: 14}}>
        {props.label}
        <span aria-hidden="true" style={{paddingLeft: 5}}>▼</span>
      </button>
      {state.isOpen &&
        <MenuPopup
          {...props}
          domProps={menuProps}
          autoFocus={state.focusStrategy}
          onClose={() => state.close()} />
      }
    </div>
  );
}

function MenuPopup(props) {
  // Create menu state based on the incoming props
  let state = useTreeState({...props, selectionMode: 'none'});

  // Get props for the menu element
  let ref = React.useRef();
  let {menuProps} = useMenu(props, state, ref);

  // Handle events that should cause the menu to close,
  // e.g. blur, clicking outside, or pressing the escape key.
  let overlayRef = React.useRef();
  let {overlayProps} = useOverlay({
    onClose: props.onClose,
    shouldCloseOnBlur: true,
    isOpen: true,
    isDismissable: true
  }, overlayRef);

  // Wrap in <FocusScope> so that focus is restored back to the
  // trigger when the menu is closed. In addition, add hidden
  // <DismissButton> components at the start and end of the list
  // to allow screen reader users to dismiss the popup easily.
  return (
    <FocusScope restoreFocus>
      <div {...overlayProps} ref={overlayRef}>
        <DismissButton onDismiss={props.onClose} />
        <ul
          {...mergeProps(menuProps, props.domProps)}
          ref={ref}
          style={{
            position: 'absolute',
            width: '100%',
            margin: '4px 0 0 0',
            padding: 0,
            listStyle: 'none',
            border: '1px solid gray',
            background: 'lightgray'
          }}>
          {[...state.collection].map(item => (
            <MenuItem
              key={item.key}
              item={item}
              state={state}
              onAction={props.onAction}
              onClose={props.onClose} />
          ))}
        </ul>
        <DismissButton onDismiss={props.onClose} />
      </div>
    </FocusScope>
  );
}

function MenuItem({item, state, onAction, onClose}) {
  // Get props for the menu item element
  let ref = React.useRef();
  let {menuItemProps} = useMenuItem({
    key: item.key,
    isDisabled: item.isDisabled,
    onAction,
    onClose
  }, state, ref);

  // Handle focus events so we can apply highlighted
  // style to the focused menu item
  let [isFocused, setFocused] = React.useState(false);
  let {focusProps} = useFocus({onFocusChange: setFocused});

  return (
    <li
      {...mergeProps(menuItemProps, focusProps)}
      ref={ref}
      style={{
        background: isFocused ? 'gray' : 'transparent',
        color: isFocused ? 'white' : 'black',
        padding: '2px 5px',
        outline: 'none',
        cursor: 'pointer'
      }}>
      {item.rendered}
    </li>
  );
}

<MenuButton label="Actions" onAction={alert}>
  <Item key="copy">Copy</Item>
  <Item key="cut">Cut</Item>
  <Item key="paste">Paste</Item>
</MenuButton>

import {useMenuTriggerState} from '@react-stately/menu';
import {useButton} from '@react-aria/button';
import {useMenu, useMenuItem} from '@react-aria/menu';
import {useTreeState} from '@react-stately/tree';
import {Item} from '@react-stately/collections';
import {mergeProps} from '@react-aria/utils';
import {FocusScope} from '@react-aria/focus';
import {useFocus} from '@react-aria/interactions';
import {
  useOverlay,
  DismissButton
} from '@react-aria/overlays';

function MenuButton(props) {
  // Create state based on the incoming props
  let state = useMenuTriggerState(props);

  // Get props for the menu trigger and menu elements
  let ref = React.useRef();
  let {menuTriggerProps, menuProps} = useMenuTrigger(
    {},
    state,
    ref
  );

  // Get props for the button based on the trigger props from useMenuTrigger
  let {buttonProps} = useButton(menuTriggerProps, ref);

  return (
    <div
      style={{
        position: 'relative',
        display: 'inline-block'
      }}>
      <button
        {...buttonProps}
        ref={ref}
        style={{height: 30, fontSize: 14}}>
        {props.label}
        <span aria-hidden="true" style={{paddingLeft: 5}}>
          ▼
        </span>
      </button>
      {state.isOpen && (
        <MenuPopup
          {...props}
          domProps={menuProps}
          autoFocus={state.focusStrategy}
          onClose={() => state.close()}
        />
      )}
    </div>
  );
}

function MenuPopup(props) {
  // Create menu state based on the incoming props
  let state = useTreeState({
    ...props,
    selectionMode: 'none'
  });

  // Get props for the menu element
  let ref = React.useRef();
  let {menuProps} = useMenu(props, state, ref);

  // Handle events that should cause the menu to close,
  // e.g. blur, clicking outside, or pressing the escape key.
  let overlayRef = React.useRef();
  let {overlayProps} = useOverlay(
    {
      onClose: props.onClose,
      shouldCloseOnBlur: true,
      isOpen: true,
      isDismissable: true
    },
    overlayRef
  );

  // Wrap in <FocusScope> so that focus is restored back to the
  // trigger when the menu is closed. In addition, add hidden
  // <DismissButton> components at the start and end of the list
  // to allow screen reader users to dismiss the popup easily.
  return (
    <FocusScope restoreFocus>
      <div {...overlayProps} ref={overlayRef}>
        <DismissButton onDismiss={props.onClose} />
        <ul
          {...mergeProps(menuProps, props.domProps)}
          ref={ref}
          style={{
            position: 'absolute',
            width: '100%',
            margin: '4px 0 0 0',
            padding: 0,
            listStyle: 'none',
            border: '1px solid gray',
            background: 'lightgray'
          }}>
          {[...state.collection].map((item) => (
            <MenuItem
              key={item.key}
              item={item}
              state={state}
              onAction={props.onAction}
              onClose={props.onClose}
            />
          ))}
        </ul>
        <DismissButton onDismiss={props.onClose} />
      </div>
    </FocusScope>
  );
}

function MenuItem({item, state, onAction, onClose}) {
  // Get props for the menu item element
  let ref = React.useRef();
  let {menuItemProps} = useMenuItem(
    {
      key: item.key,
      isDisabled: item.isDisabled,
      onAction,
      onClose
    },
    state,
    ref
  );

  // Handle focus events so we can apply highlighted
  // style to the focused menu item
  let [isFocused, setFocused] = React.useState(false);
  let {focusProps} = useFocus({onFocusChange: setFocused});

  return (
    <li
      {...mergeProps(menuItemProps, focusProps)}
      ref={ref}
      style={{
        background: isFocused ? 'gray' : 'transparent',
        color: isFocused ? 'white' : 'black',
        padding: '2px 5px',
        outline: 'none',
        cursor: 'pointer'
      }}>
      {item.rendered}
    </li>
  );
}

<MenuButton label="Actions" onAction={alert}>
  <Item key="copy">Copy</Item>
  <Item key="cut">Cut</Item>
  <Item key="paste">Paste</Item>
</MenuButton>

import {useMenuTriggerState} from '@react-stately/menu';
import {useButton} from '@react-aria/button';
import {
  useMenu,
  useMenuItem
} from '@react-aria/menu';
import {useTreeState} from '@react-stately/tree';
import {Item} from '@react-stately/collections';
import {mergeProps} from '@react-aria/utils';
import {FocusScope} from '@react-aria/focus';
import {useFocus} from '@react-aria/interactions';
import {
  useOverlay,
  DismissButton
} from '@react-aria/overlays';

function MenuButton(
  props
) {
  // Create state based on the incoming props
  let state = useMenuTriggerState(
    props
  );

  // Get props for the menu trigger and menu elements
  let ref = React.useRef();
  let {
    menuTriggerProps,
    menuProps
  } = useMenuTrigger(
    {},
    state,
    ref
  );

  // Get props for the button based on the trigger props from useMenuTrigger
  let {
    buttonProps
  } = useButton(
    menuTriggerProps,
    ref
  );

  return (
    <div
      style={{
        position:
          'relative',
        display:
          'inline-block'
      }}>
      <button
        {...buttonProps}
        ref={ref}
        style={{
          height: 30,
          fontSize: 14
        }}>
        {props.label}
        <span
          aria-hidden="true"
          style={{
            paddingLeft: 5
          }}>
          ▼
        </span>
      </button>
      {state.isOpen && (
        <MenuPopup
          {...props}
          domProps={
            menuProps
          }
          autoFocus={
            state.focusStrategy
          }
          onClose={() =>
            state.close()
          }
        />
      )}
    </div>
  );
}

function MenuPopup(
  props
) {
  // Create menu state based on the incoming props
  let state = useTreeState(
    {
      ...props,
      selectionMode:
        'none'
    }
  );

  // Get props for the menu element
  let ref = React.useRef();
  let {
    menuProps
  } = useMenu(
    props,
    state,
    ref
  );

  // Handle events that should cause the menu to close,
  // e.g. blur, clicking outside, or pressing the escape key.
  let overlayRef = React.useRef();
  let {
    overlayProps
  } = useOverlay(
    {
      onClose:
        props.onClose,
      shouldCloseOnBlur: true,
      isOpen: true,
      isDismissable: true
    },
    overlayRef
  );

  // Wrap in <FocusScope> so that focus is restored back to the
  // trigger when the menu is closed. In addition, add hidden
  // <DismissButton> components at the start and end of the list
  // to allow screen reader users to dismiss the popup easily.
  return (
    <FocusScope
      restoreFocus>
      <div
        {...overlayProps}
        ref={overlayRef}>
        <DismissButton
          onDismiss={
            props.onClose
          }
        />
        <ul
          {...mergeProps(
            menuProps,
            props.domProps
          )}
          ref={ref}
          style={{
            position:
              'absolute',
            width:
              '100%',
            margin:
              '4px 0 0 0',
            padding: 0,
            listStyle:
              'none',
            border:
              '1px solid gray',
            background:
              'lightgray'
          }}>
          {[
            ...state.collection
          ].map(
            (item) => (
              <MenuItem
                key={
                  item.key
                }
                item={
                  item
                }
                state={
                  state
                }
                onAction={
                  props.onAction
                }
                onClose={
                  props.onClose
                }
              />
            )
          )}
        </ul>
        <DismissButton
          onDismiss={
            props.onClose
          }
        />
      </div>
    </FocusScope>
  );
}

function MenuItem({
  item,
  state,
  onAction,
  onClose
}) {
  // Get props for the menu item element
  let ref = React.useRef();
  let {
    menuItemProps
  } = useMenuItem(
    {
      key: item.key,
      isDisabled:
        item.isDisabled,
      onAction,
      onClose
    },
    state,
    ref
  );

  // Handle focus events so we can apply highlighted
  // style to the focused menu item
  let [
    isFocused,
    setFocused
  ] = React.useState(
    false
  );
  let {
    focusProps
  } = useFocus({
    onFocusChange: setFocused
  });

  return (
    <li
      {...mergeProps(
        menuItemProps,
        focusProps
      )}
      ref={ref}
      style={{
        background: isFocused
          ? 'gray'
          : 'transparent',
        color: isFocused
          ? 'white'
          : 'black',
        padding:
          '2px 5px',
        outline: 'none',
        cursor: 'pointer'
      }}>
      {item.rendered}
    </li>
  );
}

<MenuButton
  label="Actions"
  onAction={alert}>
  <Item key="copy">
    Copy
  </Item>
  <Item key="cut">
    Cut
  </Item>
  <Item key="paste">
    Paste
  </Item>
</MenuButton>

Internationalization#

RTL#

In right-to-left languages, the menu button should be mirrored. The arrow should be on the left, and the label should be on the right. In addition, the content of menu items should flip. Ensure that your CSS accounts for this.

Name	Type	Description
`type`	`'menu' \| 'listbox'`	The type of menu that the menu trigger opens.

Properties

Name	Type	Description
`isOpen`	`boolean`	Whether the menu is currently open.
`focusStrategy`	`FocusStrategy`	Controls which item will be auto focused when the menu opens.

Methods

Method	Description
`setOpen( (value: boolean )): void`	Sets whether the menu is open.
`setFocusStrategy( (value: FocusStrategy )): void`	Sets which item will be auto focused when the menu opens.
`open( ( )): void`	Opens the menu.
`close( ( )): void`	Closes the menu.
`toggle( (focusStrategy: FocusStrategy \| null )): void`	Toggles the menu.

'first' | 'last'

Name	Type	Description
`menuTriggerProps`	`AriaButtonProps`	Props for the menu trigger element.
`menuProps`	`HTMLAttributes<HTMLElement>`	Props for the menu.

Name	Type	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.
`elementType`	`string \| JSXElementConstructor<any>`	The HTML element or React element used to render the button, e.g. 'div', 'a', or `RouterLink`.
`href`	`string`	A URL to link to if elementType="a".
`target`	`string`	The target window for the link.
`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'`	The behavior of the button when used in an HTML form.
`tabIndex`	`number`
`id`	`string`
`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
`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'

BaseEvent<ReactKeyboardEvent<any>>

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

Manages state for a menu trigger. Tracks whether the menu is currently open, and controls which item will receive focus when it opens.

useMenuTriggerState(
  (props: MenuTriggerProps
)): MenuTriggerState

Name	Type	Description
`align`	`Alignment`	Where the Menu aligns with its trigger.
`direction`	`'bottom' \| 'top'`	Where the Menu opens relative to its trigger.
`closeOnSelect`	`boolean`	Whether the Menu closes when a selection is made.
`isOpen`	`boolean`	Whether the Menu loads open (controlled).
`defaultOpen`	`boolean`	Whether the Menu loads open (uncontrolled).
`onOpenChange`	`( (isOpen: boolean )) => void`	Handler that is called when the Menu opens or closes.
`shouldFlip`	`boolean`	Whether the element should flip its orientation when there is insufficient space for it to render within the view.

'start' | 'end'

Provides the behavior and accessibility implementation for a menu trigger.

useMenuTrigger(
  props: MenuTriggerAriaProps,
  state: MenuTriggerState,
  ref: RefObject<HTMLElement>
): MenuTriggerAria

Provides the behavior and accessibility implementation for a button component. Handles mouse, keyboard, and touch interactions, focus behavior, and ARIA props for both native button elements and custom element types.

useButton(
  (props: AriaButtonProps,
  , ref: RefObject<HTMLElement>
)): ButtonAria

Name	Type	Description
`buttonProps`	`ButtonHTMLAttributes<HTMLButtonElement>`	Props for the button element.
`isPressed`	`boolean`	Whether the button is currently pressed.

Provides the behavior and accessibility implementation for a menu component. A menu displays a list of actions or options and allows a user to choose one.

useMenu<T>(
  props: AriaMenuOptions<T>,
  state: TreeState<T>,
  ref: RefObject<HTMLElement>
): MenuAria

Name	Type	Description
`isVirtualized`	`boolean`	Whether the menu uses virtual scrolling.
`keyboardDelegate`	`KeyboardDelegate`	An optional keyboard delegate implementation for type to select, to override the default.
`autoFocus`	`boolean \| FocusStrategy`	Where the focus should be set.
`shouldFocusWrap`	`boolean`	Whether keyboard navigation is circular.
`onAction`	`( (key: Key )) => void`	Handler that is called when an item is selected.
`children`	`CollectionChildren<T>`	The contents of the collection.
`items`	`Iterable<T>`	Item objects in the collection.
`disabledKeys`	`Iterable<Key>`	They 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 )) => any`	Handler that is called when the selection changes.
`id`	`string`
`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.

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
`title`	`ReactNode`	Rendered contents of the section, e.g. a header.
`aria-label`	`string`	An accessibility label for the section.
`children`	`ItemElement<T> \| ItemElement<T>[] \| ItemRenderer<T>`	Static child items or a function to render children.
`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>

'none' | 'single' | 'multiple'

'all' | Set<Key>

Name	Type	Description
`collection`	`Collection<Node<T>>`	A collection of items in the tree.
`disabledKeys`	`Set<Key>`	A set of keys for items that are disabled.
`expandedKeys`	`Set<Key>`	A set of keys for items that are expanded.
`toggleKey`	`( (key: Key )) => void`	Toggles the expanded state for an item by its key.
`selectionManager`	`SelectionManager`	A selection manager to read and update multiple selection state.

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`	`any`	Whether the selection is empty.
`isSelectAll`	`any`	Whether all items in the collection are selected.

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.

Name	Type	Description
`menuProps`	`HTMLAttributes<HTMLElement>`	Props for the menu element

Provides the behavior and accessibility implementation for an item in a menu. See useMenu for more details about menus.

useMenuItem<T>(
  props: AriaMenuItemProps,
  state: TreeState<T>,
  ref: RefObject<HTMLElement>
): MenuItemAria

Name	Type	Description
`isDisabled`	`boolean`	Whether the menu item is disabled.
`isSelected`	`boolean`	Whether the menu item is selected.
`aria-label`	`string`	A screen reader only label for the menu item.
`key`	`Key`	The unique key for the menu item.
`onClose`	`( ( )) => void`	Handler that is called when the menu should close after selecting an item.
`closeOnSelect`	`boolean`	Whether the menu should close when the menu item is selected.
`isVirtualized`	`boolean`	Whether the menu item is contained in a virtual scrolling menu.
`onAction`	`( (key: Key )) => void`	Handler that is called when the user activates the item.

Name	Type	Description
`menuItemProps`	`HTMLAttributes<HTMLElement>`	Props for the menu item element
`labelProps`	`HTMLAttributes<HTMLElement>`	Props for the main text element inside the menu item
`descriptionProps`	`HTMLAttributes<HTMLElement>`	Props for the description text element inside the menu item, if any
`keyboardShortcutProps`	`HTMLAttributes<HTMLElement>`	Props for the keyboard shortcut text element inside the item, if any

A FocusScope manages focus for its descendants. It supports containing focus inside the scope, restoring focus to the previously focused element on unmount, and auto focusing children on mount. It also acts as a container for a programmatic focus management interface that can be used to move focus forward and back in response to user events.

Name	Type	Description
`children`	`ReactNode`	The contents of the focus scope.
`contain`	`boolean`	Whether to contain focus inside the scope, so users cannot move focus outside, for example in a modal dialog.
`restoreFocus`	`boolean`	Whether to restore focus back to the element that was focused when the focus scope mounted, after the focus scope unmounts.
`autoFocus`	`boolean`	Whether to auto focus the first focusable element in the focus scope on mount.

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	Description
`targetRef`	`RefObject<HTMLElement>`
`overlayRef`	`RefObject<HTMLElement>`
`scrollRef`	`RefObject<HTMLElement>`
`shouldUpdatePosition`	`boolean`
`placement`	`Placement`
`containerPadding`	`number`
`offset`	`number`
`crossOffset`	`number`
`shouldFlip`	`boolean`
`boundaryElement`	`HTMLElement`
`isOpen`	`boolean`

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

Name	Type	Description
`overlayProps`	`HTMLAttributes<Element>`
`arrowProps`	`HTMLAttributes<Element>`
`placement`	`PlacementAxis`

Axis | 'center'

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