useTabList

Provides the behavior and accessibility implementation for a tab list. Tabs organize content into multiple sections and allow users to navigate between them.

install	`yarn add @react-aria/tabs`
version	3.1.0
usage	`import {useTabList, useTab, useTabPanel} from '@react-aria/tabs'`

View ARIA spec

W3C

API#

useTabList<T>(
  props: AriaTabListProps<T>,
  state: TabListState<T>,
  ref: RefObject<HTMLElement>
): TabListAria

useTab<T>(
  props: AriaTabProps,
  state: TabListState<T>,
  ref: RefObject<HTMLElement>
): TabAria

useTabPanel<T>(
  props: AriaTabPanelProps,
  state: TabListState<T>,
  ref: RefObject<HTMLElement>
): TabPanelAria

Features#

Tabs provide a list of tabs that a user can select from to switch between multiple tab panels. useTabList, useTab, and useTabPanel can be used to implement these in an accessible way.

Support for mouse, touch, and keyboard interactions on tabs
Support for LTR and RTL keyboard navigation
Support for disabled tabs
Follows the tabs ARIA pattern, semantically linking tabs and their associated tab panels
Focus management for tab panels without any focusable children

Anatomy#

Tabs consist of a tab list with one or more visually separated tabs. Each tab has associated content, and only the selected tab's content is shown. Each tab can be clicked, tapped, or navigated to via arrow keys. Depending on the keyboardActivation prop, the tab can be selected by receiving keyboard focus, or it can be selected with the Enter key.

useTabList returns props to spread onto the tab list container:

Name	Type	Description
`tabListProps`	`HTMLAttributes<HTMLElement>`	Props for the tablist container.

useTab returns props to be spread onto each individual tab:

Name	Type	Description
`tabProps`	`HTMLAttributes<HTMLElement>`	Props for the tab element.

useTabPanel returns props to spread onto the container for the tab content:

Name	Type	Description
`tabPanelProps`	`HTMLAttributes<HTMLElement>`	Props for the tab panel element.

State is managed by the useTabListState hook in @react-stately/tabs. The state object should be passed as an option to useTabList, useTab, and useTabPanel.

Example#

This example displays a basic list of tabs. The currently selected tab receives a tabIndex of 0 while the rest are set to -1 ensuring that the whole tablist is a single tab stop. The selected tab has a different style so it's obvious which one is currently selected. useTab and useTabPanel handle associating the tabs and tab panels for assistive technology. The currently selected tab panel is rendered below the list of tabs. The key prop on the TabPanel element is important to ensure that DOM state (e.g. text field contents) is not shared between unrelated tabs.

import {Item} from '@react-stately/collections';

function Tabs(props) {
  let state = useTabListState(props);
  let ref = React.useRef();
  let {tabListProps} = useTabList(props, state, ref);
  return (
    <div style={{height: '150px'}}>
      <div
        {...tabListProps}
        ref={ref}
        style={{display: 'flex', borderBottom: '1px solid grey'}}>
        {[...state.collection].map((item) => (
          <Tab key={item.key} item={item} state={state} />
        ))}
      </div>
      <TabPanel key={state.selectedItem?.key} state={state} />
    </div>
  );
}

function Tab({item, state}) {
  let {key, rendered} = item;
  let ref = React.useRef();
  let {tabProps} = useTab({key}, state, ref);
  let isSelected = state.selectedKey === key;
  let isDisabled = state.disabledKeys.has(key);
  return (
    <div
      {...tabProps}
      ref={ref}
      style={{
        padding: '10px',
        borderBottom: isSelected ? '3px solid var(--blue)' : undefined,
        opacity: isDisabled ? '0.5' : undefined
      }}>
      {rendered}
    </div>
  );
}

function TabPanel({state, ...props}) {
  let ref = React.useRef();
  let {tabPanelProps} = useTabPanel(props, state, ref);
  return (
    <div {...tabPanelProps} ref={ref} style={{padding: '10px'}}>
      {state.selectedItem?.props.children}
    </div>
  );
}

<Tabs aria-label="History of Ancient Rome" disabledKeys={['Emp']}>
  <Item key="FoR" title="Founding of Rome">
    Arma virumque cano, Troiae qui primus ab oris.
  </Item>
  <Item key="MaR" title="Monarchy and Republic">
    Senatus Populusque Romanus.
  </Item>
  <Item key="Emp" title="Empire">
    Alea jacta est.
  </Item>
</Tabs>

import {Item} from '@react-stately/collections';

function Tabs(props) {
  let state = useTabListState(props);
  let ref = React.useRef();
  let {tabListProps} = useTabList(props, state, ref);
  return (
    <div style={{height: '150px'}}>
      <div
        {...tabListProps}
        ref={ref}
        style={{
          display: 'flex',
          borderBottom: '1px solid grey'
        }}>
        {[...state.collection].map((item) => (
          <Tab key={item.key} item={item} state={state} />
        ))}
      </div>
      <TabPanel
        key={state.selectedItem?.key}
        state={state}
      />
    </div>
  );
}

function Tab({item, state}) {
  let {key, rendered} = item;
  let ref = React.useRef();
  let {tabProps} = useTab({key}, state, ref);
  let isSelected = state.selectedKey === key;
  let isDisabled = state.disabledKeys.has(key);
  return (
    <div
      {...tabProps}
      ref={ref}
      style={{
        padding: '10px',
        borderBottom: isSelected
          ? '3px solid var(--blue)'
          : undefined,
        opacity: isDisabled ? '0.5' : undefined
      }}>
      {rendered}
    </div>
  );
}

function TabPanel({state, ...props}) {
  let ref = React.useRef();
  let {tabPanelProps} = useTabPanel(props, state, ref);
  return (
    <div
      {...tabPanelProps}
      ref={ref}
      style={{padding: '10px'}}>
      {state.selectedItem?.props.children}
    </div>
  );
}

<Tabs
  aria-label="History of Ancient Rome"
  disabledKeys={['Emp']}>
  <Item key="FoR" title="Founding of Rome">
    Arma virumque cano, Troiae qui primus ab oris.
  </Item>
  <Item key="MaR" title="Monarchy and Republic">
    Senatus Populusque Romanus.
  </Item>
  <Item key="Emp" title="Empire">
    Alea jacta est.
  </Item>
</Tabs>

import {Item} from '@react-stately/collections';

function Tabs(props) {
  let state = useTabListState(
    props
  );
  let ref = React.useRef();
  let {
    tabListProps
  } = useTabList(
    props,
    state,
    ref
  );
  return (
    <div
      style={{
        height: '150px'
      }}>
      <div
        {...tabListProps}
        ref={ref}
        style={{
          display:
            'flex',
          borderBottom:
            '1px solid grey'
        }}>
        {[
          ...state.collection
        ].map((item) => (
          <Tab
            key={
              item.key
            }
            item={item}
            state={state}
          />
        ))}
      </div>
      <TabPanel
        key={
          state
            .selectedItem
            ?.key
        }
        state={state}
      />
    </div>
  );
}

function Tab({
  item,
  state
}) {
  let {
    key,
    rendered
  } = item;
  let ref = React.useRef();
  let {
    tabProps
  } = useTab(
    {key},
    state,
    ref
  );
  let isSelected =
    state.selectedKey ===
    key;
  let isDisabled = state.disabledKeys.has(
    key
  );
  return (
    <div
      {...tabProps}
      ref={ref}
      style={{
        padding: '10px',
        borderBottom: isSelected
          ? '3px solid var(--blue)'
          : undefined,
        opacity: isDisabled
          ? '0.5'
          : undefined
      }}>
      {rendered}
    </div>
  );
}

function TabPanel({
  state,
  ...props
}) {
  let ref = React.useRef();
  let {
    tabPanelProps
  } = useTabPanel(
    props,
    state,
    ref
  );
  return (
    <div
      {...tabPanelProps}
      ref={ref}
      style={{
        padding: '10px'
      }}>
      {
        state
          .selectedItem
          ?.props
          .children
      }
    </div>
  );
}

<Tabs
  aria-label="History of Ancient Rome"
  disabledKeys={[
    'Emp'
  ]}>
  <Item
    key="FoR"
    title="Founding of Rome">
    Arma virumque cano,
    Troiae qui primus
    ab oris.
  </Item>
  <Item
    key="MaR"
    title="Monarchy and Republic">
    Senatus Populusque
    Romanus.
  </Item>
  <Item
    key="Emp"
    title="Empire">
    Alea jacta est.
  </Item>
</Tabs>

With focusable content#

When the tab panel doesn't contain any focusable content, the entire panel is given a tabIndex=0 so that the content can be navigated to with the keyboard. When the tab panel contains focusable content, such as a textfield, then the tabIndex is omitted because the content itself can receive focus.

This example uses the same Tabs component from above. Try navigating from the tabs to the content for each panel using the keyboard.

<Tabs aria-label="Notes app">
  <Item key="item1" title="Jane Doe">
    <label>
      Leave a note for Jane: <input type="text" />
    </label>
  </Item>
  <Item key="item2" title="John Doe">
    Senatus Populusque Romanus.
  </Item>
  <Item key="item3" title="Joe Bloggs">
    Alea jacta est.
  </Item>
</Tabs>

<Tabs aria-label="Notes app">
  <Item key="item1" title="Jane Doe">
    <label>
      Leave a note for Jane: <input type="text" />
    </label>
  </Item>
  <Item key="item2" title="John Doe">
    Senatus Populusque Romanus.
  </Item>
  <Item key="item3" title="Joe Bloggs">
    Alea jacta est.
  </Item>
</Tabs>

<Tabs aria-label="Notes app">
  <Item
    key="item1"
    title="Jane Doe">
    <label>
      Leave a note for
      Jane:{' '}
      <input type="text" />
    </label>
  </Item>
  <Item
    key="item2"
    title="John Doe">
    Senatus Populusque
    Romanus.
  </Item>
  <Item
    key="item3"
    title="Joe Bloggs">
    Alea jacta est.
  </Item>
</Tabs>

Internationalization#

useTabList handles some aspects of internationalization automatically. For example, keyboard navigation is automatically mirrored for right-to-left languages. You are responsible for localizing all tab labels and content.

RTL#

In right-to-left languages, the tablist should be mirrored. The first tab is furthest right and the last tab is furthest left. Ensure that your CSS accounts for this.

Name	Type	Default	Description
`children`	`CollectionChildren<T>`	—	The contents of the collection.
`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.
`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.
`keyboardActivation`	`'automatic' \| 'manual'`	`'automatic'`	Whether tabs are activated automatically on focus or manually.
`orientation`	`Orientation`	`'horizontal'`	The orientation of the tabs.
`isDisabled`	`boolean`	—	Whether the Tabs are disabled. Shows that a selection exists, but is not available in that circumstance.
`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.

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>

'horizontal' | 'vertical'

Properties

Name	Type	Description
`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.

Methods

Method	Description
`setSelectedKey( (key: Key )): void`	Sets the selected key.

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.
`at( (idx: number )): T`	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.

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`

Methods

Method	Description
`setSelectionBehavior( (selectionBehavior: SelectionBehavior )): void`	Sets the selection behavior for the collection.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key, , 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`

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.
`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 \| \| ( (v: Selection )) => 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.

'none'
  | 'single'
  | 'multiple'

'toggle' | 'replace'

'all' | Set<Key>

'first' | 'last'

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.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.

'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`	`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.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.

Name	Type	Description
`tabListProps`	`HTMLAttributes<HTMLElement>`	Props for the tablist container.

Name	Type	Description
`key`	`Key`	The key of the tab.
`isDisabled`	`boolean`	Whether the tab should be disabled.

Name	Type	Description
`tabProps`	`HTMLAttributes<HTMLElement>`	Props for the tab element.

Name	Type	Description
`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
`tabPanelProps`	`HTMLAttributes<HTMLElement>`	Props for the tab panel element.

Provides state management for a Tabs component. Tabs include a TabList which tracks which tab is currently selected and displays the content associated with that Tab in a TabPanel.

useTabListState<T>(
  (props: TabListProps<T>
)): TabListState<T>

Name	Type	Description
`children`	`CollectionChildren<T>`	The contents of the collection.
`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.
`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.