useTagGroup

Provides the behavior and accessibility implementation for a tag group component. A tag group is a focusable list of labels, categories, keywords, filters, or other items, with support for keyboard navigation, selection, and removal.

install	`yarn add react-aria`
version	3.32.0
usage	`import {useTagGroup} from 'react-aria'`

View repository

GitHub

View package

NPM

API#

useTagGroup<T>(
  props: AriaTagGroupOptions<T>,
  state: ListState<T>,
  ref: RefObject<HTMLElement>
): TagGroupAria

useTag<T>(
  props: AriaTagProps<T>,
  state: ListState<T>,
  ref: RefObject<FocusableElement>
): TagAria

Features#

Exposed to assistive technology as a grid using ARIA
Keyboard navigation support including arrow keys, home/end, page up/down, and delete
Keyboard focus management and cross browser normalization
Labeling support for accessibility
Support for mouse, touch, and keyboard interactions

Anatomy#

A tag group consists of a list of tags. If a visual label is not provided, then an aria-label or aria-labelledby prop must be passed to identify the tag group to assistive technology.

Individual tags should include a visual label, and may optionally include icons or a remove button.

useTagGroup returns props for the group and its label, which you should spread onto the appropriate element:

Name	Type	Description
`gridProps`	`DOMAttributes`	Props for the tag grouping element.
`labelProps`	`DOMAttributes`	Props for the tag group's visible label (if any).
`descriptionProps`	`DOMAttributes`	Props for the tag group description element, if any.
`errorMessageProps`	`DOMAttributes`	Props for the tag group error message element, if any.

useTag returns props for an individual tag, along with states that you can use for styling:

Name	Type	Description
`rowProps`	`DOMAttributes`	Props for the tag row element.
`gridCellProps`	`DOMAttributes`	Props for the tag cell element.
`removeButtonProps`	`AriaButtonProps`	Props for the tag remove button.
`allowsRemoving`	`boolean`	Whether the tag can be removed.
`isPressed`	`boolean`	Whether the item is currently in a pressed state.
`isSelected`	`boolean`	Whether the item is currently selected.
`isFocused`	`boolean`	Whether the item is currently focused.
`isDisabled`	`boolean`	Whether the item is non-interactive, i.e. both selection and actions are disabled and the item may not be focused. Dependent on `disabledKeys` and `disabledBehavior`.
`allowsSelection`	`boolean`	Whether the item may be selected, dependent on `selectionMode`, `disabledKeys`, and `disabledBehavior`.

In order to be correctly identified to assistive technologies and enable proper keyboard navigation, the tag group should use gridProps on its outer container.

Each individual tag should use rowProps on its outer container, and use gridCellProps on an inner container.

Example#

import type {ListState} from 'react-stately';
import type {AriaTagGroupProps, AriaTagProps} from 'react-aria';
import {Item, useListState} from 'react-stately';
import {useFocusRing, useTag, useTagGroup} from 'react-aria';

// Reuse the Button from your component library. See below for details.
import {Button} from 'your-component-library';

function TagGroup<T extends object>(props: AriaTagGroupProps<T>) {
  let { label, description, errorMessage } = props;
  let ref = React.useRef(null);

  let state = useListState(props);
  let {
    gridProps,
    labelProps,
    descriptionProps,
    errorMessageProps
  } = useTagGroup(props, state, ref);

  return (
    <div className="tag-group">
      <div {...labelProps}>{label}</div>
      <div {...gridProps} ref={ref}>
        {[...state.collection].map((item) => (
          <Tag
            key={item.key}
            item={item}
            state={state}
          />
        ))}
      </div>
      {description && (
        <div {...descriptionProps} className="description">
          {description}
        </div>
      )}
      {errorMessage && (
        <div {...errorMessageProps} className="error-message">
          {errorMessage}
        </div>
      )}
    </div>
  );
}

interface TagProps<T> extends AriaTagProps<T> {
  state: ListState<T>;
}

function Tag<T>(props: TagProps<T>) {
  let { item, state } = props;
  let ref = React.useRef(null);
  let { focusProps, isFocusVisible } = useFocusRing({ within: true });
  let { rowProps, gridCellProps, removeButtonProps, allowsRemoving } = useTag(
    props,
    state,
    ref
  );

  return (
    <div
      ref={ref}
      {...rowProps}
      {...focusProps}
      data-focus-visible={isFocusVisible}
    >
      <div {...gridCellProps}>
        {item.rendered}
        {allowsRemoving && <Button {...removeButtonProps}>❎</Button>}
      </div>
    </div>
  );
}

<TagGroup label="Categories">
  <Item key="news">News</Item>
  <Item key="travel">Travel</Item>
  <Item key="gaming">Gaming</Item>
  <Item key="shopping">Shopping</Item>
</TagGroup>

import type {ListState} from 'react-stately';
import type {
  AriaTagGroupProps,
  AriaTagProps
} from 'react-aria';
import {Item, useListState} from 'react-stately';
import {
  useFocusRing,
  useTag,
  useTagGroup
} from 'react-aria';

// Reuse the Button from your component library. See below for details.
import {Button} from 'your-component-library';

function TagGroup<T extends object>(
  props: AriaTagGroupProps<T>
) {
  let { label, description, errorMessage } = props;
  let ref = React.useRef(null);

  let state = useListState(props);
  let {
    gridProps,
    labelProps,
    descriptionProps,
    errorMessageProps
  } = useTagGroup(props, state, ref);

  return (
    <div className="tag-group">
      <div {...labelProps}>{label}</div>
      <div {...gridProps} ref={ref}>
        {[...state.collection].map((item) => (
          <Tag
            key={item.key}
            item={item}
            state={state}
          />
        ))}
      </div>
      {description && (
        <div {...descriptionProps} className="description">
          {description}
        </div>
      )}
      {errorMessage && (
        <div
          {...errorMessageProps}
          className="error-message"
        >
          {errorMessage}
        </div>
      )}
    </div>
  );
}

interface TagProps<T> extends AriaTagProps<T> {
  state: ListState<T>;
}

function Tag<T>(props: TagProps<T>) {
  let { item, state } = props;
  let ref = React.useRef(null);
  let { focusProps, isFocusVisible } = useFocusRing({
    within: true
  });
  let {
    rowProps,
    gridCellProps,
    removeButtonProps,
    allowsRemoving
  } = useTag(props, state, ref);

  return (
    <div
      ref={ref}
      {...rowProps}
      {...focusProps}
      data-focus-visible={isFocusVisible}
    >
      <div {...gridCellProps}>
        {item.rendered}
        {allowsRemoving && (
          <Button {...removeButtonProps}>❎</Button>
        )}
      </div>
    </div>
  );
}

<TagGroup label="Categories">
  <Item key="news">News</Item>
  <Item key="travel">Travel</Item>
  <Item key="gaming">Gaming</Item>
  <Item key="shopping">Shopping</Item>
</TagGroup>

import type {ListState} from 'react-stately';
import type {
  AriaTagGroupProps,
  AriaTagProps
} from 'react-aria';
import {
  Item,
  useListState
} from 'react-stately';
import {
  useFocusRing,
  useTag,
  useTagGroup
} from 'react-aria';

// Reuse the Button from your component library. See below for details.
import {Button} from 'your-component-library';

function TagGroup<
  T extends object
>(
  props:
    AriaTagGroupProps<T>
) {
  let {
    label,
    description,
    errorMessage
  } = props;
  let ref = React.useRef(
    null
  );

  let state =
    useListState(props);
  let {
    gridProps,
    labelProps,
    descriptionProps,
    errorMessageProps
  } = useTagGroup(
    props,
    state,
    ref
  );

  return (
    <div className="tag-group">
      <div
        {...labelProps}
      >
        {label}
      </div>
      <div
        {...gridProps}
        ref={ref}
      >
        {[
          ...state
            .collection
        ].map((item) => (
          <Tag
            key={item
              .key}
            item={item}
            state={state}
          />
        ))}
      </div>
      {description && (
        <div
          {...descriptionProps}
          className="description"
        >
          {description}
        </div>
      )}
      {errorMessage && (
        <div
          {...errorMessageProps}
          className="error-message"
        >
          {errorMessage}
        </div>
      )}
    </div>
  );
}

interface TagProps<T>
  extends
    AriaTagProps<T> {
  state: ListState<T>;
}

function Tag<T>(
  props: TagProps<T>
) {
  let { item, state } =
    props;
  let ref = React.useRef(
    null
  );
  let {
    focusProps,
    isFocusVisible
  } = useFocusRing({
    within: true
  });
  let {
    rowProps,
    gridCellProps,
    removeButtonProps,
    allowsRemoving
  } = useTag(
    props,
    state,
    ref
  );

  return (
    <div
      ref={ref}
      {...rowProps}
      {...focusProps}
      data-focus-visible={isFocusVisible}
    >
      <div
        {...gridCellProps}
      >
        {item.rendered}
        {allowsRemoving &&
          (
            <Button
              {...removeButtonProps}
            >
              ❎
            </Button>
          )}
      </div>
    </div>
  );
}

<TagGroup label="Categories">
  <Item key="news">
    News
  </Item>
  <Item key="travel">
    Travel
  </Item>
  <Item key="gaming">
    Gaming
  </Item>
  <Item key="shopping">
    Shopping
  </Item>
</TagGroup>

Show CSS

.tag-group {
  display: flex;
  flex-direction: column;
  gap: 4px;
}

.tag-group [role="grid"] {
  display: flex;
  flex-wrap: wrap;
  gap: 4px;
}

.tag-group [role="row"] {
  display: flex;
  align-items: center;
  border: 1px solid gray;
  border-radius: 4px;
  padding: 2px 5px;
  cursor: default;
  outline: none;

  &[data-focus-visible=true] {
    outline: 2px solid slateblue;
    outline-offset: 2px;
  }

  &[aria-selected=true] {
    background: var(--spectrum-gray-900);
    border-color: var(--spectrum-gray-900);
    color: var(--spectrum-gray-50);
  }

  &[aria-disabled] {
    opacity: 0.4;
  }
}

.tag-group [role="gridcell"] {
  margin: 0 5px;
}

.tag-group [role="row"] button {
  background: none;
  border: none;
  padding-right: 0;
}

.tag-group .description {
  font-size: 12px;
}

.tag-group .error-message {
  color: red;
  font-size: 12px;
}

.tag-group {
  display: flex;
  flex-direction: column;
  gap: 4px;
}

.tag-group [role="grid"] {
  display: flex;
  flex-wrap: wrap;
  gap: 4px;
}

.tag-group [role="row"] {
  display: flex;
  align-items: center;
  border: 1px solid gray;
  border-radius: 4px;
  padding: 2px 5px;
  cursor: default;
  outline: none;

  &[data-focus-visible=true] {
    outline: 2px solid slateblue;
    outline-offset: 2px;
  }

  &[aria-selected=true] {
    background: var(--spectrum-gray-900);
    border-color: var(--spectrum-gray-900);
    color: var(--spectrum-gray-50);
  }

  &[aria-disabled] {
    opacity: 0.4;
  }
}

.tag-group [role="gridcell"] {
  margin: 0 5px;
}

.tag-group [role="row"] button {
  background: none;
  border: none;
  padding-right: 0;
}

.tag-group .description {
  font-size: 12px;
}

.tag-group .error-message {
  color: red;
  font-size: 12px;
}

.tag-group {
  display: flex;
  flex-direction: column;
  gap: 4px;
}

.tag-group [role="grid"] {
  display: flex;
  flex-wrap: wrap;
  gap: 4px;
}

.tag-group [role="row"] {
  display: flex;
  align-items: center;
  border: 1px solid gray;
  border-radius: 4px;
  padding: 2px 5px;
  cursor: default;
  outline: none;

  &[data-focus-visible=true] {
    outline: 2px solid slateblue;
    outline-offset: 2px;
  }

  &[aria-selected=true] {
    background: var(--spectrum-gray-900);
    border-color: var(--spectrum-gray-900);
    color: var(--spectrum-gray-50);
  }

  &[aria-disabled] {
    opacity: 0.4;
  }
}

.tag-group [role="gridcell"] {
  margin: 0 5px;
}

.tag-group [role="row"] button {
  background: none;
  border: none;
  padding-right: 0;
}

.tag-group .description {
  font-size: 12px;
}

.tag-group .error-message {
  color: red;
  font-size: 12px;
}

Button#

The Button component is used in the above example to remove a tag. It is built using the useButton hook, and can be shared with many other components.

Show code

import {useButton} from 'react-aria';

function Button(props) {
  let ref = React.useRef(null);
  let { buttonProps } = useButton(props, ref);
  return <button {...buttonProps} ref={ref}>{props.children}</button>;
}

import {useButton} from 'react-aria';

function Button(props) {
  let ref = React.useRef(null);
  let { buttonProps } = useButton(props, ref);
  return (
    <button {...buttonProps} ref={ref}>
      {props.children}
    </button>
  );
}

import {useButton} from 'react-aria';

function Button(props) {
  let ref = React.useRef(
    null
  );
  let { buttonProps } =
    useButton(
      props,
      ref
    );
  return (
    <button
      {...buttonProps}
      ref={ref}
    >
      {props.children}
    </button>
  );
}

Styled examples#

Tailwind CSS

A TagGroup built with Tailwind.

Usage#

Remove tags#

The onRemove prop can be used to include a remove button which can be used to remove a tag. This allows the user to press the remove button, or press the backspace key while the tag is focused to remove the tag from the group. Additionally, when selection is enabled, all selected items will be deleted when pressing the backspace key on a selected tag.

import {useListData} from 'react-stately';

function Example() {
  let list = useListData({
    initialItems: [
      { id: 1, name: 'News' },
      { id: 2, name: 'Travel' },
      { id: 3, name: 'Gaming' },
      { id: 4, name: 'Shopping' }
    ]
  });

  return (
    <TagGroup
      label="Categories"
      items={list.items}
      onRemove={(keys) => list.remove(...keys)}
    >
      {(item) => <Item>{item.name}</Item>}
    </TagGroup>
  );
}

import {useListData} from 'react-stately';

function Example() {
  let list = useListData({
    initialItems: [
      { id: 1, name: 'News' },
      { id: 2, name: 'Travel' },
      { id: 3, name: 'Gaming' },
      { id: 4, name: 'Shopping' }
    ]
  });

  return (
    <TagGroup
      label="Categories"
      items={list.items}
      onRemove={(keys) => list.remove(...keys)}
    >
      {(item) => <Item>{item.name}</Item>}
    </TagGroup>
  );
}

import {useListData} from 'react-stately';

function Example() {
  let list = useListData(
    {
      initialItems: [
        {
          id: 1,
          name: 'News'
        },
        {
          id: 2,
          name: 'Travel'
        },
        {
          id: 3,
          name: 'Gaming'
        },
        {
          id: 4,
          name:
            'Shopping'
        }
      ]
    }
  );

  return (
    <TagGroup
      label="Categories"
      items={list.items}
      onRemove={(keys) =>
        list.remove(
          ...keys
        )}
    >
      {(item) => (
        <Item>
          {item.name}
        </Item>
      )}
    </TagGroup>
  );
}

Selection#

TagGroup supports multiple selection modes. By default, selection is disabled, however this can be changed using the selectionMode prop. Use defaultSelectedKeys to provide a default set of selected items (uncontrolled) and selectedKeys to set the selected items (controlled). The value of the selected keys must match the key prop of the items. See the react-stately Selection docs for more details.

import type {Selection} from 'react-stately';

function Example() {
  let [selected, setSelected] = React.useState<Selection>(new Set(['parking']));

  return (
    <>
      <TagGroup
        label="Amenities"
        selectionMode="multiple"
        selectedKeys={selected}
        onSelectionChange={setSelected}
      >
        <Item key="laundry">Laundry</Item>
        <Item key="fitness">Fitness center</Item>
        <Item key="parking">Parking</Item>
        <Item key="pool">Swimming pool</Item>
        <Item key="breakfast">Breakfast</Item>
      </TagGroup>
      <p>
        Current selection (controlled):{' '}
        {selected === 'all' ? 'all' : [...selected].join(', ')}
      </p>
    </>
  );
}

import type {Selection} from 'react-stately';

function Example() {
  let [selected, setSelected] = React.useState<Selection>(
    new Set(['parking'])
  );

  return (
    <>
      <TagGroup
        label="Amenities"
        selectionMode="multiple"
        selectedKeys={selected}
        onSelectionChange={setSelected}
      >
        <Item key="laundry">Laundry</Item>
        <Item key="fitness">Fitness center</Item>
        <Item key="parking">Parking</Item>
        <Item key="pool">Swimming pool</Item>
        <Item key="breakfast">Breakfast</Item>
      </TagGroup>
      <p>
        Current selection (controlled): {selected === 'all'
          ? 'all'
          : [...selected].join(', ')}
      </p>
    </>
  );
}

import type {Selection} from 'react-stately';

function Example() {
  let [
    selected,
    setSelected
  ] = React.useState<
    Selection
  >(
    new Set(['parking'])
  );

  return (
    <>
      <TagGroup
        label="Amenities"
        selectionMode="multiple"
        selectedKeys={selected}
        onSelectionChange={setSelected}
      >
        <Item key="laundry">
          Laundry
        </Item>
        <Item key="fitness">
          Fitness center
        </Item>
        <Item key="parking">
          Parking
        </Item>
        <Item key="pool">
          Swimming pool
        </Item>
        <Item key="breakfast">
          Breakfast
        </Item>
      </TagGroup>
      <p>
        Current selection
        (controlled):
        {' '}
        {selected ===
            'all'
          ? 'all'
          : [...selected]
            .join(', ')}
      </p>
    </>
  );
}

Links#

Tags may be links to another page or website. This can be achieved by passing the href prop to the <Item> component. Tags with an href are not selectable.

<TagGroup label="Links">
  <Item href="https://adobe.com/" target="_blank">Adobe</Item>
  <Item href="https://apple.com/" target="_blank">Apple</Item>
  <Item href="https://google.com/" target="_blank">Google</Item>
  <Item href="https://microsoft.com/" target="_blank">Microsoft</Item>
</TagGroup>

<TagGroup label="Links">
  <Item href="https://adobe.com/" target="_blank">
    Adobe
  </Item>
  <Item href="https://apple.com/" target="_blank">
    Apple
  </Item>
  <Item href="https://google.com/" target="_blank">
    Google
  </Item>
  <Item href="https://microsoft.com/" target="_blank">
    Microsoft
  </Item>
</TagGroup>

<TagGroup label="Links">
  <Item
    href="https://adobe.com/"
    target="_blank"
  >
    Adobe
  </Item>
  <Item
    href="https://apple.com/"
    target="_blank"
  >
    Apple
  </Item>
  <Item
    href="https://google.com/"
    target="_blank"
  >
    Google
  </Item>
  <Item
    href="https://microsoft.com/"
    target="_blank"
  >
    Microsoft
  </Item>
</TagGroup>

Client side routing#

The <Item> component works with frameworks and client side routers like Next.js and React Router. As with other React Aria components that support links, this works via the RouterProvider component at the root of your app. See the client side routing guide to learn how to set this up.

Disabled tags#

TagGroup supports marking items as disabled using the disabledKeys prop. Each key in this list corresponds with the key prop passed to the Item component, or automatically derived from the values passed to the items prop. Disabled items are not focusable, selectable, or keyboard navigable. See Collections for more details.

<TagGroup
  label="Sandwich contents"
  selectionMode="multiple"
  disabledKeys={['tuna']}
>
  <Item key="lettuce">Lettuce</Item>
  <Item key="tomato">Tomato</Item>
  <Item key="cheese">Cheese</Item>
  <Item key="tuna">Tuna Salad</Item>
  <Item key="egg">Egg Salad</Item>
  <Item key="ham">Ham</Item>
</TagGroup>

<TagGroup
  label="Sandwich contents"
  selectionMode="multiple"
  disabledKeys={['tuna']}
>
  <Item key="lettuce">Lettuce</Item>
  <Item key="tomato">Tomato</Item>
  <Item key="cheese">Cheese</Item>
  <Item key="tuna">Tuna Salad</Item>
  <Item key="egg">Egg Salad</Item>
  <Item key="ham">Ham</Item>
</TagGroup>

<TagGroup
  label="Sandwich contents"
  selectionMode="multiple"
  disabledKeys={[
    'tuna'
  ]}
>
  <Item key="lettuce">
    Lettuce
  </Item>
  <Item key="tomato">
    Tomato
  </Item>
  <Item key="cheese">
    Cheese
  </Item>
  <Item key="tuna">
    Tuna Salad
  </Item>
  <Item key="egg">
    Egg Salad
  </Item>
  <Item key="ham">
    Ham
  </Item>
</TagGroup>

Description#

The description prop can be used to associate additional help text with a tag group.

<TagGroup label="Categories" description="Your selected categories.">
  <Item key="news">News</Item>
  <Item key="travel">Travel</Item>
  <Item key="gaming">Gaming</Item>
  <Item key="shopping">Shopping</Item>
</TagGroup>

<TagGroup
  label="Categories"
  description="Your selected categories."
>
  <Item key="news">News</Item>
  <Item key="travel">Travel</Item>
  <Item key="gaming">Gaming</Item>
  <Item key="shopping">Shopping</Item>
</TagGroup>

<TagGroup
  label="Categories"
  description="Your selected categories."
>
  <Item key="news">
    News
  </Item>
  <Item key="travel">
    Travel
  </Item>
  <Item key="gaming">
    Gaming
  </Item>
  <Item key="shopping">
    Shopping
  </Item>
</TagGroup>

Error message#

The errorMessage prop can be used to help the user fix a validation error.

<TagGroup label="Categories" errorMessage="Invalid set of categories.">
  <Item key="news">News</Item>
  <Item key="travel">Travel</Item>
  <Item key="gaming">Gaming</Item>
  <Item key="shopping">Shopping</Item>
</TagGroup>

<TagGroup
  label="Categories"
  errorMessage="Invalid set of categories."
>
  <Item key="news">News</Item>
  <Item key="travel">Travel</Item>
  <Item key="gaming">Gaming</Item>
  <Item key="shopping">Shopping</Item>
</TagGroup>

<TagGroup
  label="Categories"
  errorMessage="Invalid set of categories."
>
  <Item key="news">
    News
  </Item>
  <Item key="travel">
    Travel
  </Item>
  <Item key="gaming">
    Gaming
  </Item>
  <Item key="shopping">
    Shopping
  </Item>
</TagGroup>

Name	Type	Description
`keyboardDelegate`	`KeyboardDelegate`	An optional keyboard delegate to handle arrow key navigation, to override the default.
`selectionBehavior`	`SelectionBehavior`	How multiple selection should behave in the collection.
`onRemove`	`( (keys: Set<Key> )) => void`	Handler that is called when a user deletes a tag.
`errorMessage`	`ReactNode`	An error message for the field.
`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 )) => any`	Handler that is called when the selection changes.
`id`	`string`	The element's unique identifier. See MDN.
`label`	`ReactNode`	The content to display as the label.
`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.
`description`	`ReactNode`	A description for the field. Provides a hint such as specific requirements for what to choose.

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, , global?: boolean )): Key \| null`	Returns the first key, or `null` for none.
`getLastKey( (key?: Key, , global?: boolean )): Key \| null`	Returns the last key, or `null` for none.
`getKeyForSearch( (search: string, , fromKey?: Key )): Key \| null`	Returns the next key after `fromKey` that matches the given search string, or `null` for none.

'toggle' | 'replace'

string | number

'none'
  | 'single'
  | 'multiple'

'all' | Set<Key>

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.

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.

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 heirarchy.
`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.
`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 \| 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.

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.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy`	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`

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`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy`	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, , child?: FocusStrategy )): void`	Sets the focused key, and optionally, whether the first or last child of that key should receive focus.

'selection' | 'all'

'first' | 'last'

Name	Type	Description
`allowsCellSelection`	`boolean`

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.

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.

Name	Type	Description
`gridProps`	`DOMAttributes`	Props for the tag grouping element.
`labelProps`	`DOMAttributes`	Props for the tag group's visible label (if any).
`descriptionProps`	`DOMAttributes`	Props for the tag group description element, if any.
`errorMessageProps`	`DOMAttributes`	Props for the tag group error message element, if any.

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	Description
`item`	`Node<T>`	An object representing the tag. Contains all the relevant information that makes up the tag.

Name	Type	Description
`rowProps`	`DOMAttributes`	Props for the tag row element.
`gridCellProps`	`DOMAttributes`	Props for the tag cell element.
`removeButtonProps`	`AriaButtonProps`	Props for the tag remove button.
`allowsRemoving`	`boolean`	Whether the tag can be removed.
`isPressed`	`boolean`	Whether the item is currently in a pressed state.
`isSelected`	`boolean`	Whether the item is currently selected.
`isFocused`	`boolean`	Whether the item is currently focused.
`isDisabled`	`boolean`	Whether the item is non-interactive, i.e. both selection and actions are disabled and the item may not be focused. Dependent on `disabledKeys` and `disabledBehavior`.
`allowsSelection`	`boolean`	Whether the item may be selected, dependent on `selectionMode`, `disabledKeys`, and `disabledBehavior`.

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

BaseEvent<ReactKeyboardEvent<any>>

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

A RouterProvider accepts a navigate function from a framework or client side router, and provides it to all nested React Aria links to enable client side navigation.

Name	Type	Description
`navigate`	`( (path: string )) => void`
`children`	`ReactNode`