Tabs

Tabs organize content into multiple sections and allow users to navigate between them.

install	`yarn add react-aria-components`
version	1.4.0
usage	`import {Tabs} from 'react-aria-components'`

View ARIA pattern

W3C

Example#

import {Tabs, TabList, Tab, TabPanel} from 'react-aria-components';

<Tabs>
  <TabList aria-label="History of Ancient Rome">
    <Tab id="FoR">Founding of Rome</Tab>
    <Tab id="MaR">Monarchy and Republic</Tab>
    <Tab id="Emp">Empire</Tab>
  </TabList>
  <TabPanel id="FoR">
    Arma virumque cano, Troiae qui primus ab oris.
  </TabPanel>
  <TabPanel id="MaR">
    Senatus Populusque Romanus.
  </TabPanel>
  <TabPanel id="Emp">
    Alea jacta est.
  </TabPanel>
</Tabs>

import {
  Tab,
  TabList,
  TabPanel,
  Tabs
} from 'react-aria-components';

<Tabs>
  <TabList aria-label="History of Ancient Rome">
    <Tab id="FoR">Founding of Rome</Tab>
    <Tab id="MaR">Monarchy and Republic</Tab>
    <Tab id="Emp">Empire</Tab>
  </TabList>
  <TabPanel id="FoR">
    Arma virumque cano, Troiae qui primus ab oris.
  </TabPanel>
  <TabPanel id="MaR">
    Senatus Populusque Romanus.
  </TabPanel>
  <TabPanel id="Emp">
    Alea jacta est.
  </TabPanel>
</Tabs>

import {
  Tab,
  TabList,
  TabPanel,
  Tabs
} from 'react-aria-components';

<Tabs>
  <TabList aria-label="History of Ancient Rome">
    <Tab id="FoR">
      Founding of Rome
    </Tab>
    <Tab id="MaR">
      Monarchy and
      Republic
    </Tab>
    <Tab id="Emp">
      Empire
    </Tab>
  </TabList>
  <TabPanel id="FoR">
    Arma virumque cano,
    Troiae qui primus
    ab oris.
  </TabPanel>
  <TabPanel id="MaR">
    Senatus Populusque
    Romanus.
  </TabPanel>
  <TabPanel id="Emp">
    Alea jacta est.
  </TabPanel>
</Tabs>

Show CSS

@import "@react-aria/example-theme";

.react-aria-Tabs {
  display: flex;
  color: var(--text-color);

  &[data-orientation=horizontal] {
    flex-direction: column;
  }
}

.react-aria-TabList {
  display: flex;

  &[data-orientation=horizontal] {
    border-bottom: 1px solid var(--border-color);

    .react-aria-Tab {
      border-bottom: 3px solid var(--border-color);
    }
  }
}

.react-aria-Tab {
  padding: 10px;
  cursor: default;
  outline: none;
  position: relative;
  color: var(--text-color-base);
  transition: color 200ms;
  --border-color: transparent;
  forced-color-adjust: none;

  &[data-hovered],
  &[data-focused] {
    color: var(--text-color-hover);
  }

  &[data-selected] {
    --border-color: var(--highlight-background);
    color: var(--text-color);
  }

  &[data-disabled] {
    color: var(--text-color-disabled);
    &[data-selected] {
      --border-color: var(--text-color-disabled);
    }
  }

  &[data-focus-visible]:after {
    content: '';
    position: absolute;
    inset: 4px;
    border-radius: 4px;
    border: 2px solid var(--focus-ring-color);
  }
}

.react-aria-TabPanel {
  margin-top: 4px;
  padding: 10px;
  border-radius: 4px;
  outline: none;

  &[data-focus-visible] {
    outline: 2px solid var(--focus-ring-color);
  }
}

@import "@react-aria/example-theme";

.react-aria-Tabs {
  display: flex;
  color: var(--text-color);

  &[data-orientation=horizontal] {
    flex-direction: column;
  }
}

.react-aria-TabList {
  display: flex;

  &[data-orientation=horizontal] {
    border-bottom: 1px solid var(--border-color);

    .react-aria-Tab {
      border-bottom: 3px solid var(--border-color);
    }
  }
}

.react-aria-Tab {
  padding: 10px;
  cursor: default;
  outline: none;
  position: relative;
  color: var(--text-color-base);
  transition: color 200ms;
  --border-color: transparent;
  forced-color-adjust: none;

  &[data-hovered],
  &[data-focused] {
    color: var(--text-color-hover);
  }

  &[data-selected] {
    --border-color: var(--highlight-background);
    color: var(--text-color);
  }

  &[data-disabled] {
    color: var(--text-color-disabled);
    &[data-selected] {
      --border-color: var(--text-color-disabled);
    }
  }

  &[data-focus-visible]:after {
    content: '';
    position: absolute;
    inset: 4px;
    border-radius: 4px;
    border: 2px solid var(--focus-ring-color);
  }
}

.react-aria-TabPanel {
  margin-top: 4px;
  padding: 10px;
  border-radius: 4px;
  outline: none;

  &[data-focus-visible] {
    outline: 2px solid var(--focus-ring-color);
  }
}

@import "@react-aria/example-theme";

.react-aria-Tabs {
  display: flex;
  color: var(--text-color);

  &[data-orientation=horizontal] {
    flex-direction: column;
  }
}

.react-aria-TabList {
  display: flex;

  &[data-orientation=horizontal] {
    border-bottom: 1px solid var(--border-color);

    .react-aria-Tab {
      border-bottom: 3px solid var(--border-color);
    }
  }
}

.react-aria-Tab {
  padding: 10px;
  cursor: default;
  outline: none;
  position: relative;
  color: var(--text-color-base);
  transition: color 200ms;
  --border-color: transparent;
  forced-color-adjust: none;

  &[data-hovered],
  &[data-focused] {
    color: var(--text-color-hover);
  }

  &[data-selected] {
    --border-color: var(--highlight-background);
    color: var(--text-color);
  }

  &[data-disabled] {
    color: var(--text-color-disabled);
    &[data-selected] {
      --border-color: var(--text-color-disabled);
    }
  }

  &[data-focus-visible]:after {
    content: '';
    position: absolute;
    inset: 4px;
    border-radius: 4px;
    border: 2px solid var(--focus-ring-color);
  }
}

.react-aria-TabPanel {
  margin-top: 4px;
  padding: 10px;
  border-radius: 4px;
  outline: none;

  &[data-focus-visible] {
    outline: 2px solid var(--focus-ring-color);
  }
}

Features#

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

Flexible – Support for both horizontal and vertical orientations, disabled tabs, customizable layout, and multiple keyboard activation modes.
Accessible – Follows the ARIA tabs pattern, automatically linking tabs and their associated tab panels semantically. The arrow keys can be used to navigate between tabs, and tab panels automatically become focusable when they don't contain any focusable children.
International – Keyboard navigation is automatically mirrored in right-to-left languages.
Styleable – Hover, press, keyboard focus, and selection states are provided for easy styling. These states only apply when interacting with an appropriate input device, unlike CSS pseudo classes.

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.

import {Tabs, TabList, Tab, TabPanel} from 'react-aria-components';

<Tabs>
  <TabList>
    <Tab />
  </TabList>
  <TabPanel />
</Tabs>

import {
  Tab,
  TabList,
  TabPanel,
  Tabs
} from 'react-aria-components';

<Tabs>
  <TabList>
    <Tab />
  </TabList>
  <TabPanel />
</Tabs>

import {
  Tab,
  TabList,
  TabPanel,
  Tabs
} from 'react-aria-components';

<Tabs>
  <TabList>
    <Tab />
  </TabList>
  <TabPanel />
</Tabs>

Concepts#

Tabs makes use of the following concepts:

Collections

Defining collections of items, async loading, and updating items over time.

Selection

Interactions and data structures to represent selection.

Examples#

Category Tabs

An article category tabs component styled with Tailwind CSS.

Swipeable Tabs

A swipeable Tabs component built with Framer Motion and CSS scroll snapping.

Starter kits#

To help kick-start your project, we offer starter kits that include example implementations of all React Aria components with various styling solutions. All components are fully styled, including support for dark mode, high contrast mode, and all UI states. Each starter comes with a pre-configured Storybook that you can experiment with, or use as a starting point for your own component library.

Selection#

Default selection#

A default selected tab can be provided using the defaultSelectedKey prop, which should correspond to the id prop provided to each item. When Tabs is used with dynamic items as described below, the key of each item is derived from the data. See the Selection guide for more details.

<Tabs defaultSelectedKey="keyboard">
  <TabList aria-label="Input settings">
    <Tab id="mouse">Mouse Settings</Tab>
    <Tab id="keyboard">Keyboard Settings</Tab>
    <Tab id="gamepad">Gamepad Settings</Tab>
  </TabList>
  <TabPanel id="mouse">Mouse Settings</TabPanel>
  <TabPanel id="keyboard">Keyboard Settings</TabPanel>
  <TabPanel id="gamepad">Gamepad Settings</TabPanel>
</Tabs>

<Tabs defaultSelectedKey="keyboard">
  <TabList aria-label="Input settings">
    <Tab id="mouse">Mouse Settings</Tab>
    <Tab id="keyboard">Keyboard Settings</Tab>
    <Tab id="gamepad">Gamepad Settings</Tab>
  </TabList>
  <TabPanel id="mouse">Mouse Settings</TabPanel>
  <TabPanel id="keyboard">Keyboard Settings</TabPanel>
  <TabPanel id="gamepad">Gamepad Settings</TabPanel>
</Tabs>

<Tabs defaultSelectedKey="keyboard">
  <TabList aria-label="Input settings">
    <Tab id="mouse">
      Mouse Settings
    </Tab>
    <Tab id="keyboard">
      Keyboard Settings
    </Tab>
    <Tab id="gamepad">
      Gamepad Settings
    </Tab>
  </TabList>
  <TabPanel id="mouse">
    Mouse Settings
  </TabPanel>
  <TabPanel id="keyboard">
    Keyboard Settings
  </TabPanel>
  <TabPanel id="gamepad">
    Gamepad Settings
  </TabPanel>
</Tabs>

Controlled selection#

Selection can be controlled using the selectedKey prop, paired with the onSelectionChange event. The id prop from the selected tab will be passed into the callback when the tab is selected, allowing you to update state accordingly.

import type {Key} from 'react-aria-components';

function Example() {
  let [timePeriod, setTimePeriod] = React.useState<Key>('triassic');

  return (
    <>
      <p>Selected time period: {timePeriod}</p>
      <Tabs selectedKey={timePeriod} onSelectionChange={setTimePeriod}>
        <TabList aria-label="Mesozoic time periods">
          <Tab id="triassic">Triassic</Tab>
          <Tab id="jurassic">Jurassic</Tab>
          <Tab id="cretaceous">Cretaceous</Tab>
        </TabList>
        <TabPanel id="triassic">
          The Triassic ranges roughly from 252 million to 201 million years ago,
          preceding the Jurassic Period.
        </TabPanel>
        <TabPanel id="jurassic">
          The Jurassic ranges from 200 million years to 145 million years ago.
        </TabPanel>
        <TabPanel id="cretaceous">
          The Cretaceous is the longest period of the Mesozoic, spanning from
          145 million to 66 million years ago.
        </TabPanel>
      </Tabs>
    </>
  );
}

import type {Key} from 'react-aria-components';

function Example() {
  let [timePeriod, setTimePeriod] = React.useState<Key>(
    'triassic'
  );

  return (
    <>
      <p>Selected time period: {timePeriod}</p>
      <Tabs
        selectedKey={timePeriod}
        onSelectionChange={setTimePeriod}
      >
        <TabList aria-label="Mesozoic time periods">
          <Tab id="triassic">Triassic</Tab>
          <Tab id="jurassic">Jurassic</Tab>
          <Tab id="cretaceous">Cretaceous</Tab>
        </TabList>
        <TabPanel id="triassic">
          The Triassic ranges roughly from 252 million to
          201 million years ago, preceding the Jurassic
          Period.
        </TabPanel>
        <TabPanel id="jurassic">
          The Jurassic ranges from 200 million years to 145
          million years ago.
        </TabPanel>
        <TabPanel id="cretaceous">
          The Cretaceous is the longest period of the
          Mesozoic, spanning from 145 million to 66 million
          years ago.
        </TabPanel>
      </Tabs>
    </>
  );
}

import type {Key} from 'react-aria-components';

function Example() {
  let [
    timePeriod,
    setTimePeriod
  ] = React.useState<
    Key
  >('triassic');

  return (
    <>
      <p>
        Selected time
        period:{' '}
        {timePeriod}
      </p>
      <Tabs
        selectedKey={timePeriod}
        onSelectionChange={setTimePeriod}
      >
        <TabList aria-label="Mesozoic time periods">
          <Tab id="triassic">
            Triassic
          </Tab>
          <Tab id="jurassic">
            Jurassic
          </Tab>
          <Tab id="cretaceous">
            Cretaceous
          </Tab>
        </TabList>
        <TabPanel id="triassic">
          The Triassic
          ranges roughly
          from 252
          million to 201
          million years
          ago, preceding
          the Jurassic
          Period.
        </TabPanel>
        <TabPanel id="jurassic">
          The Jurassic
          ranges from 200
          million years
          to 145 million
          years ago.
        </TabPanel>
        <TabPanel id="cretaceous">
          The Cretaceous
          is the longest
          period of the
          Mesozoic,
          spanning from
          145 million to
          66 million
          years ago.
        </TabPanel>
      </Tabs>
    </>
  );
}

Keyboard Activation#

By default, pressing the arrow keys while focus is on a Tab will switch selection to the adjacent Tab in that direction, updating the content displayed accordingly. If you would like to prevent selection change from happening automatically you can set the keyboardActivation prop to "manual". This will prevent tab selection from changing on arrow key press, requiring a subsequent Enter or Space key press to confirm tab selection.

<Tabs keyboardActivation="manual">
  <TabList aria-label="Input settings">
    <Tab id="mouse">Mouse Settings</Tab>
    <Tab id="keyboard">Keyboard Settings</Tab>
    <Tab id="gamepad">Gamepad Settings</Tab>
  </TabList>
  <TabPanel id="mouse">Mouse Settings</TabPanel>
  <TabPanel id="keyboard">Keyboard Settings</TabPanel>
  <TabPanel id="gamepad">Gamepad Settings</TabPanel>
</Tabs>

<Tabs keyboardActivation="manual">
  <TabList aria-label="Input settings">
    <Tab id="mouse">Mouse Settings</Tab>
    <Tab id="keyboard">Keyboard Settings</Tab>
    <Tab id="gamepad">Gamepad Settings</Tab>
  </TabList>
  <TabPanel id="mouse">Mouse Settings</TabPanel>
  <TabPanel id="keyboard">Keyboard Settings</TabPanel>
  <TabPanel id="gamepad">Gamepad Settings</TabPanel>
</Tabs>

<Tabs keyboardActivation="manual">
  <TabList aria-label="Input settings">
    <Tab id="mouse">
      Mouse Settings
    </Tab>
    <Tab id="keyboard">
      Keyboard Settings
    </Tab>
    <Tab id="gamepad">
      Gamepad Settings
    </Tab>
  </TabList>
  <TabPanel id="mouse">
    Mouse Settings
  </TabPanel>
  <TabPanel id="keyboard">
    Keyboard Settings
  </TabPanel>
  <TabPanel id="gamepad">
    Gamepad Settings
  </TabPanel>
</Tabs>

Content#

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>
  <TabList aria-label="Notes app">
    <Tab id="1">Jane Doe</Tab>
    <Tab id="2">John Doe</Tab>
    <Tab id="3">Joe Bloggs</Tab>
  </TabList>
  <TabPanel id="1">
    <label>Leave a note for Jane: <input type="text" /></label>
  </TabPanel>
  <TabPanel id="2">Senatus Populusque Romanus.</TabPanel>
  <TabPanel id="3">Alea jacta est.</TabPanel>
</Tabs>

<Tabs>
  <TabList aria-label="Notes app">
    <Tab id="1">Jane Doe</Tab>
    <Tab id="2">John Doe</Tab>
    <Tab id="3">Joe Bloggs</Tab>
  </TabList>
  <TabPanel id="1">
    <label>
      Leave a note for Jane: <input type="text" />
    </label>
  </TabPanel>
  <TabPanel id="2">Senatus Populusque Romanus.</TabPanel>
  <TabPanel id="3">Alea jacta est.</TabPanel>
</Tabs>

<Tabs>
  <TabList aria-label="Notes app">
    <Tab id="1">
      Jane Doe
    </Tab>
    <Tab id="2">
      John Doe
    </Tab>
    <Tab id="3">
      Joe Bloggs
    </Tab>
  </TabList>
  <TabPanel id="1">
    <label>
      Leave a note for
      Jane:{' '}
      <input type="text" />
    </label>
  </TabPanel>
  <TabPanel id="2">
    Senatus Populusque
    Romanus.
  </TabPanel>
  <TabPanel id="3">
    Alea jacta est.
  </TabPanel>
</Tabs>

Dynamic items#

The above examples have shown tabs with static items. The items prop can be used when creating tabs from a dynamic collection, for example when the user can add and remove tabs, or the tabs come from an external data source. The function passed as the children of the TabList component is called for each item in the list, and returns an <Tab>. A function passed as the children of the Collection component returns a corresponding <TabPanel> for each tab.

Each item accepts an id prop, which is passed to the onSelectionChange handler to identify the selected item. Alternatively, if the item objects contain an id property, as shown in the example below, then this is used automatically and an id prop is not required. See Collection Components for more details.

import {Collection, Button} from 'react-aria-components';

function Example() {
  let [tabs, setTabs] = React.useState([
    {id: 1, title: 'Tab 1', content: 'Tab body 1'},
    {id: 2, title: 'Tab 2', content: 'Tab body 2'},
    {id: 3, title: 'Tab 3', content: 'Tab body 3'}
  ]);

  let addTab = () => {
    setTabs(tabs => [
      ...tabs,
      {
        id: tabs.length + 1,
        title: `Tab ${tabs.length + 1}`,
        content: `Tab body ${tabs.length + 1}`
      }
    ]);
  };

  let removeTab = () => {
    if (tabs.length > 1) {
      setTabs(tabs => tabs.slice(0, -1));
    }
  };

  return (
    <Tabs>
      <div style={{display: 'flex'}}>
        <TabList aria-label="Dynamic tabs" items={tabs} style={{flex: 1}}>
          {item => <Tab>{item.title}</Tab>}
        </TabList>
        <div className="button-group">
          <Button onPress={addTab}>Add tab</Button>
          <Button onPress={removeTab}>Remove tab</Button>
        </div>
      </div>
      <Collection items={tabs}>
        {item => <TabPanel>{item.content}</TabPanel>}
      </Collection>
    </Tabs>
  );
}

import {Button, Collection} from 'react-aria-components';

function Example() {
  let [tabs, setTabs] = React.useState([
    { id: 1, title: 'Tab 1', content: 'Tab body 1' },
    { id: 2, title: 'Tab 2', content: 'Tab body 2' },
    { id: 3, title: 'Tab 3', content: 'Tab body 3' }
  ]);

  let addTab = () => {
    setTabs((tabs) => [
      ...tabs,
      {
        id: tabs.length + 1,
        title: `Tab ${tabs.length + 1}`,
        content: `Tab body ${tabs.length + 1}`
      }
    ]);
  };

  let removeTab = () => {
    if (tabs.length > 1) {
      setTabs((tabs) => tabs.slice(0, -1));
    }
  };

  return (
    <Tabs>
      <div style={{ display: 'flex' }}>
        <TabList
          aria-label="Dynamic tabs"
          items={tabs}
          style={{ flex: 1 }}
        >
          {(item) => <Tab>{item.title}</Tab>}
        </TabList>
        <div className="button-group">
          <Button onPress={addTab}>Add tab</Button>
          <Button onPress={removeTab}>Remove tab</Button>
        </div>
      </div>
      <Collection items={tabs}>
        {(item) => <TabPanel>{item.content}</TabPanel>}
      </Collection>
    </Tabs>
  );
}

import {
  Button,
  Collection
} from 'react-aria-components';

function Example() {
  let [tabs, setTabs] =
    React.useState([
      {
        id: 1,
        title: 'Tab 1',
        content:
          'Tab body 1'
      },
      {
        id: 2,
        title: 'Tab 2',
        content:
          'Tab body 2'
      },
      {
        id: 3,
        title: 'Tab 3',
        content:
          'Tab body 3'
      }
    ]);

  let addTab = () => {
    setTabs((tabs) => [
      ...tabs,
      {
        id: tabs.length +
          1,
        title: `Tab ${
          tabs.length + 1
        }`,
        content:
          `Tab body ${
            tabs.length +
            1
          }`
      }
    ]);
  };

  let removeTab = () => {
    if (
      tabs.length > 1
    ) {
      setTabs((tabs) =>
        tabs.slice(0, -1)
      );
    }
  };

  return (
    <Tabs>
      <div
        style={{
          display: 'flex'
        }}
      >
        <TabList
          aria-label="Dynamic tabs"
          items={tabs}
          style={{
            flex: 1
          }}
        >
          {(item) => (
            <Tab>
              {item
                .title}
            </Tab>
          )}
        </TabList>
        <div className="button-group">
          <Button
            onPress={addTab}
          >
            Add tab
          </Button>
          <Button
            onPress={removeTab}
          >
            Remove tab
          </Button>
        </div>
      </div>
      <Collection
        items={tabs}
      >
        {(item) => (
          <TabPanel>
            {item
              .content}
          </TabPanel>
        )}
      </Collection>
    </Tabs>
  );
}

Show CSS

.button-group {
  border-bottom: 1px solid gray;
  display: flex;
  align-items: center;
  gap: 8px;
}

.button-group {
  border-bottom: 1px solid gray;
  display: flex;
  align-items: center;
  gap: 8px;
}

.button-group {
  border-bottom: 1px solid gray;
  display: flex;
  align-items: center;
  gap: 8px;
}

Orientation#

By default, tabs are horizontally oriented. The orientation prop can be set to vertical to change this. This does not affect keyboard navigation. You are responsible for styling your tabs accordingly.

<Tabs orientation="vertical">
  <TabList aria-label="Chat log orientation example">
    <Tab id="1">John Doe</Tab>
    <Tab id="2">Jane Doe</Tab>
    <Tab id="3">Joe Bloggs</Tab>
  </TabList>
  <TabPanel id="1">There is no prior chat history with John Doe.</TabPanel>
  <TabPanel id="2">There is no prior chat history with Jane Doe.</TabPanel>
  <TabPanel id="3">There is no prior chat history with Joe Bloggs.</TabPanel>
</Tabs>

<Tabs orientation="vertical">
  <TabList aria-label="Chat log orientation example">
    <Tab id="1">John Doe</Tab>
    <Tab id="2">Jane Doe</Tab>
    <Tab id="3">Joe Bloggs</Tab>
  </TabList>
  <TabPanel id="1">
    There is no prior chat history with John Doe.
  </TabPanel>
  <TabPanel id="2">
    There is no prior chat history with Jane Doe.
  </TabPanel>
  <TabPanel id="3">
    There is no prior chat history with Joe Bloggs.
  </TabPanel>
</Tabs>

<Tabs orientation="vertical">
  <TabList aria-label="Chat log orientation example">
    <Tab id="1">
      John Doe
    </Tab>
    <Tab id="2">
      Jane Doe
    </Tab>
    <Tab id="3">
      Joe Bloggs
    </Tab>
  </TabList>
  <TabPanel id="1">
    There is no prior
    chat history with
    John Doe.
  </TabPanel>
  <TabPanel id="2">
    There is no prior
    chat history with
    Jane Doe.
  </TabPanel>
  <TabPanel id="3">
    There is no prior
    chat history with
    Joe Bloggs.
  </TabPanel>
</Tabs>

Show CSS

.react-aria-Tabs {
  &[data-orientation=vertical] {
    flex-direction: row;
  }
}

.react-aria-TabList {
  &[data-orientation=vertical] {
    flex-direction: column;
    border-inline-end: 1px solid gray;

    .react-aria-Tab {
      border-inline-end: 3px solid var(--border-color, transparent);
    }
  }
}

.react-aria-Tabs {
  &[data-orientation=vertical] {
    flex-direction: row;
  }
}

.react-aria-TabList {
  &[data-orientation=vertical] {
    flex-direction: column;
    border-inline-end: 1px solid gray;

    .react-aria-Tab {
      border-inline-end: 3px solid var(--border-color, transparent);
    }
  }
}

.react-aria-Tabs {
  &[data-orientation=vertical] {
    flex-direction: row;
  }
}

.react-aria-TabList {
  &[data-orientation=vertical] {
    flex-direction: column;
    border-inline-end: 1px solid gray;

    .react-aria-Tab {
      border-inline-end: 3px solid var(--border-color, transparent);
    }
  }
}

Disabled#

All tabs can be disabled using the isDisabled prop.

<Tabs isDisabled>
  <TabList aria-label="Input settings">
    <Tab id="mouse">Mouse Settings</Tab>
    <Tab id="keyboard">Keyboard Settings</Tab>
    <Tab id="gamepad">Gamepad Settings</Tab>
  </TabList>
  <TabPanel id="mouse">Mouse Settings</TabPanel>
  <TabPanel id="keyboard">Keyboard Settings</TabPanel>
  <TabPanel id="gamepad">Gamepad Settings</TabPanel>
</Tabs>

<Tabs isDisabled>
  <TabList aria-label="Input settings">
    <Tab id="mouse">Mouse Settings</Tab>
    <Tab id="keyboard">Keyboard Settings</Tab>
    <Tab id="gamepad">Gamepad Settings</Tab>
  </TabList>
  <TabPanel id="mouse">Mouse Settings</TabPanel>
  <TabPanel id="keyboard">Keyboard Settings</TabPanel>
  <TabPanel id="gamepad">Gamepad Settings</TabPanel>
</Tabs>

<Tabs isDisabled>
  <TabList aria-label="Input settings">
    <Tab id="mouse">
      Mouse Settings
    </Tab>
    <Tab id="keyboard">
      Keyboard Settings
    </Tab>
    <Tab id="gamepad">
      Gamepad Settings
    </Tab>
  </TabList>
  <TabPanel id="mouse">
    Mouse Settings
  </TabPanel>
  <TabPanel id="keyboard">
    Keyboard Settings
  </TabPanel>
  <TabPanel id="gamepad">
    Gamepad Settings
  </TabPanel>
</Tabs>

Show CSS

.react-aria-Tab {
  &[data-disabled] {
    color: var(--text-color-disabled);
    &[data-selected] {
      --border-color: var(--border-color-disabled);
    }
  }
}

.react-aria-Tab {
  &[data-disabled] {
    color: var(--text-color-disabled);
    &[data-selected] {
      --border-color: var(--border-color-disabled);
    }
  }
}

.react-aria-Tab {
  &[data-disabled] {
    color: var(--text-color-disabled);
    &[data-selected] {
      --border-color: var(--border-color-disabled);
    }
  }
}

Disabled items#

An individual Tab can be disabled with the isDisabled prop. Disabled tabs are not focusable, selectable, or keyboard navigable.

<Tabs>
  <TabList aria-label="Input settings">
    <Tab id="mouse">Mouse Settings</Tab>
    <Tab id="keyboard">Keyboard Settings</Tab>
    <Tab id="gamepad" isDisabled>Gamepad Settings</Tab>  </TabList>
  <TabPanel id="mouse">Mouse Settings</TabPanel>
  <TabPanel id="keyboard">Keyboard Settings</TabPanel>
  <TabPanel id="gamepad">Gamepad Settings</TabPanel>
</Tabs>

<Tabs>
  <TabList aria-label="Input settings">
    <Tab id="mouse">Mouse Settings</Tab>
    <Tab id="keyboard">Keyboard Settings</Tab>
    <Tab id="gamepad" isDisabled>Gamepad Settings</Tab>  </TabList>
  <TabPanel id="mouse">Mouse Settings</TabPanel>
  <TabPanel id="keyboard">Keyboard Settings</TabPanel>
  <TabPanel id="gamepad">Gamepad Settings</TabPanel>
</Tabs>

<Tabs>
  <TabList aria-label="Input settings">
    <Tab id="mouse">
      Mouse Settings
    </Tab>
    <Tab id="keyboard">
      Keyboard Settings
    </Tab>
    <Tab
      id="gamepad"
      isDisabled
    >
      Gamepad Settings
    </Tab>  </TabList>
  <TabPanel id="mouse">
    Mouse Settings
  </TabPanel>
  <TabPanel id="keyboard">
    Keyboard Settings
  </TabPanel>
  <TabPanel id="gamepad">
    Gamepad Settings
  </TabPanel>
</Tabs>

In dynamic collections, it may be more convenient to use the disabledKeys prop at the Tabs level instead of isDisabled on individual tabs. Each key in this list corresponds with the id prop passed to the Tab component, or automatically derived from the values passed to the items prop (see the Collections for more details). A tab is considered disabled if its id exists in disabledKeys or if it has isDisabled.

function Example() {
  let tabs = [
    {id: 1, title: 'Mouse settings'},
    {id: 2, title: 'Keyboard settings'},
    {id: 3, title: 'Gamepad settings'}
  ];

  return (
    <Tabs disabledKeys={[2]}>
      <TabList aria-label="Input settings" items={tabs}>
        {item => <Tab>{item.title}</Tab>}
      </TabList>
      <Collection items={tabs}>
        {item => <TabPanel>{item.title}</TabPanel>}
      </Collection>
    </Tabs>
  );
}

function Example() {
  let tabs = [
    {id: 1, title: 'Mouse settings'},
    {id: 2, title: 'Keyboard settings'},
    {id: 3, title: 'Gamepad settings'}
  ];

  return (
    <Tabs disabledKeys={[2]}>
      <TabList aria-label="Input settings" items={tabs}>
        {item => <Tab>{item.title}</Tab>}
      </TabList>
      <Collection items={tabs}>
        {item => <TabPanel>{item.title}</TabPanel>}
      </Collection>
    </Tabs>
  );
}

function Example() {
  let tabs = [
    {
      id: 1,
      title:
        'Mouse settings'
    },
    {
      id: 2,
      title:
        'Keyboard settings'
    },
    {
      id: 3,
      title:
        'Gamepad settings'
    }
  ];

  return (
    <Tabs
      disabledKeys={[2]}
    >
      <TabList
        aria-label="Input settings"
        items={tabs}
      >
        {(item) => (
          <Tab>
            {item.title}
          </Tab>
        )}
      </TabList>
      <Collection
        items={tabs}
      >
        {(item) => (
          <TabPanel>
            {item.title}
          </TabPanel>
        )}
      </Collection>
    </Tabs>
  );
}

Links#

Tabs may be rendered as links to different routes in your application. This can be achieved by passing the href prop to the <Tab> component. By default, links perform native browser navigation. However, you'll usually want to synchronize the selected tab with the URL from your client side router. This takes two steps:

Set up a RouterProvider at the root of your app. This will handle link navigation from all React Aria components using your framework or router. See the client side routing guide to learn how to set this up.
Use the selectedKey prop to set the selected tab based on the URL, as described above.

This example uses React Router to setup routes for each tab and synchronize the selection with the URL.

import {BrowserRouter, Route, Routes, useLocation, useNavigate} from 'react-router-dom';
import {RouterProvider} from 'react-aria-components';

function AppTabs() {
  let { pathname } = useLocation();

  return (
    <Tabs selectedKey={pathname}>
      <TabList aria-label="Tabs">
        <Tab id="/" href="/">Home</Tab>
        <Tab id="/shared" href="/shared">Shared</Tab>
        <Tab id="/deleted" href="/deleted">Deleted</Tab>
      </TabList>
      <TabPanel id={pathname}>
        <Routes>
          <Route path="/" element={<HomePage />} />
          <Route path="/shared" element={<SharedPage />} />
          <Route path="/deleted" element={<DeletedPage />} />
        </Routes>
      </TabPanel>
    </Tabs>
  );
}

function App() {
  let navigate = useNavigate();
  return (
    <RouterProvider navigate={navigate}>
      <Routes>
        <Route path="/*" element={<AppTabs />} />
      </Routes>
    </RouterProvider>
  );
}

<BrowserRouter>
  <App />
</BrowserRouter>

import {
  BrowserRouter,
  Route,
  Routes,
  useLocation,
  useNavigate
} from 'react-router-dom';
import {RouterProvider} from 'react-aria-components';

function AppTabs() {
  let { pathname } = useLocation();

  return (
    <Tabs selectedKey={pathname}>
      <TabList aria-label="Tabs">
        <Tab id="/" href="/">Home</Tab>
        <Tab id="/shared" href="/shared">Shared</Tab>
        <Tab id="/deleted" href="/deleted">Deleted</Tab>
      </TabList>
      <TabPanel id={pathname}>
        <Routes>
          <Route path="/" element={<HomePage />} />
          <Route path="/shared" element={<SharedPage />} />
          <Route
            path="/deleted"
            element={<DeletedPage />}
          />
        </Routes>
      </TabPanel>
    </Tabs>
  );
}

function App() {
  let navigate = useNavigate();
  return (
    <RouterProvider navigate={navigate}>
      <Routes>
        <Route path="/*" element={<AppTabs />} />
      </Routes>
    </RouterProvider>
  );
}

<BrowserRouter>
  <App />
</BrowserRouter>

import {
  BrowserRouter,
  Route,
  Routes,
  useLocation,
  useNavigate
} from 'react-router-dom';
import {RouterProvider} from 'react-aria-components';

function AppTabs() {
  let { pathname } =
    useLocation();

  return (
    <Tabs
      selectedKey={pathname}
    >
      <TabList aria-label="Tabs">
        <Tab
          id="/"
          href="/"
        >
          Home
        </Tab>
        <Tab
          id="/shared"
          href="/shared"
        >
          Shared
        </Tab>
        <Tab
          id="/deleted"
          href="/deleted"
        >
          Deleted
        </Tab>
      </TabList>
      <TabPanel
        id={pathname}
      >
        <Routes>
          <Route
            path="/"
            element={
              <HomePage />
            }
          />
          <Route
            path="/shared"
            element={
              <SharedPage />
            }
          />
          <Route
            path="/deleted"
            element={
              <DeletedPage />
            }
          />
        </Routes>
      </TabPanel>
    </Tabs>
  );
}

function App() {
  let navigate =
    useNavigate();
  return (
    <RouterProvider
      navigate={navigate}
    >
      <Routes>
        <Route
          path="/*"
          element={
            <AppTabs />
          }
        />
      </Routes>
    </RouterProvider>
  );
}

<BrowserRouter>
  <App />
</BrowserRouter>

Props#

Tabs#

Name	Type	Default	Description
`isDisabled`	`boolean`	—	Whether the TabList is disabled. Shows that a selection exists, but is not available in that circumstance.
`disabledKeys`	`Iterable<Key>`	—	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`selectedKey`	`Key \| null`	—	The currently selected key in the collection (controlled).
`defaultSelectedKey`	`Key`	—	The initial selected key in the collection (uncontrolled).
`keyboardActivation`	`'automatic' \| 'manual'`	`'automatic'`	Whether tabs are activated automatically on focus or manually.
`orientation`	`Orientation`	`'horizontal'`	The orientation of the tabs.
`children`	`ReactNode \| ( (values: TabsRenderProps & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	—	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: TabsRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: TabsRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	—	The inline style for the element. A function may be provided to compute the style based on component state.

Events

Name	Type	Description
`onSelectionChange`	`( (key: Key )) => void`	Handler that is called when the selection changes.

Layout

Name	Type	Description
`slot`	`string \| null`	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.

Accessibility

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.

TabList#

Name	Type	Description
`className`	`string \| ( (values: TabListRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: TabListRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	The inline style for the element. A function may be provided to compute the style based on component state.
`children`	`ReactNode \| ( (item: T )) => ReactNode`	The contents of the collection.
`dependencies`	`any[]`	Values that should invalidate the item cache when using dynamic collections.
`items`	`Iterable<T>`	Item objects in the collection.

Accessibility

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

Tab#

Name	Type	Description
`id`	`Key`	The unique id of the tab.
`isDisabled`	`boolean`	Whether the tab is disabled.
`children`	`ReactNode \| ( (values: TabRenderProps & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: TabRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: TabRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	The inline style for the element. A function may be provided to compute the style based on component state.
`href`	`Href`	A URL to link to. See MDN.
`hrefLang`	`string`	Hints at the human language of the linked URL. SeeMDN.
`target`	`HTMLAttributeAnchorTarget`	The target window for the link. See MDN.
`rel`	`string`	The relationship between the linked resource and the current page. See MDN.
`download`	`boolean \| string`	Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.
`ping`	`string`	A space-separated list of URLs to ping when the link is followed. See MDN.
`referrerPolicy`	`HTMLAttributeReferrerPolicy`	How much of the referrer to send when following the link. See MDN.
`routerOptions`	`RouterOptions`	Options for the configured client side router.

Events

Name	Type	Description
`onHoverStart`	`( (e: HoverEvent )) => void`	Handler that is called when a hover interaction starts.
`onHoverEnd`	`( (e: HoverEvent )) => void`	Handler that is called when a hover interaction ends.
`onHoverChange`	`( (isHovering: boolean )) => void`	Handler that is called when the hover state changes.

Accessibility

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

TabPanel#

Name	Type	Default	Description
`shouldForceMount`	`boolean`	`false`	Whether to mount the tab panel in the DOM even when it is not currently selected. Inactive tab panels are inert and cannot be interacted with. They must be styled appropriately so this is clear to the user visually.
`children`	`ReactNode \| ( (values: TabPanelRenderProps & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	—	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: TabPanelRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: TabPanelRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	—	The inline style for the element. A function may be provided to compute the style based on component state.

Accessibility

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.

Styling#

React Aria components can be styled in many ways, including using CSS classes, inline styles, utility classes (e.g. Tailwind), CSS-in-JS (e.g. Styled Components), etc. By default, all components include a builtin className attribute which can be targeted using CSS selectors. These follow the react-aria-ComponentName naming convention.

.react-aria-Tabs {
  /* ... */
}

.react-aria-Tabs {
  /* ... */
}

.react-aria-Tabs {
  /* ... */
}

A custom className can also be specified on any component. This overrides the default className provided by React Aria with your own.

<Tabs className="my-tabs">
  {/* ... */}
</Tabs>

<Tabs className="my-tabs">
  {/* ... */}
</Tabs>

<Tabs className="my-tabs">
  {/* ... */}
</Tabs>

In addition, some components support multiple UI states (e.g. pressed, hovered, etc.). React Aria components expose states using data attributes, which you can target in CSS selectors. For example:

.react-aria-Tab[data-selected] {
  /* ... */
}

.react-aria-Tab[data-focus-visible] {
  /* ... */
}

.react-aria-Tab[data-selected] {
  /* ... */
}

.react-aria-Tab[data-focus-visible] {
  /* ... */
}

.react-aria-Tab[data-selected] {
  /* ... */
}

.react-aria-Tab[data-focus-visible] {
  /* ... */
}

The className and style props also accept functions which receive states for styling. This lets you dynamically determine the classes or styles to apply, which is useful when using utility CSS libraries like Tailwind.

<Tab
  className={({ isSelected }) => isSelected ? 'bg-blue-400' : 'bg-gray-100'}
>
  Settings
</Tab>

<Tab
  className={({ isSelected }) =>
    isSelected ? 'bg-blue-400' : 'bg-gray-100'}
>
  Settings
</Tab>

<Tab
  className={(
    { isSelected }
  ) =>
    isSelected
      ? 'bg-blue-400'
      : 'bg-gray-100'}
>
  Settings
</Tab>

Render props may also be used as children to alter what elements are rendered based on the current state. For example, you could render an extra element when an item is selected.

<Tab>
  {({isSelected}) => (
    <>
      {isSelected && <SelectionIndicator />}
      Item
    </>
  )}
</Tab>

<Tab>
  {({isSelected}) => (
    <>
      {isSelected && <SelectionIndicator />}
      Item
    </>
  )}
</Tab>

<Tab>
  {(
    { isSelected }
  ) => (
    <>
      {isSelected && (
        <SelectionIndicator />
      )}
      Item
    </>
  )}
</Tab>

The states and selectors for each component used in Tabs are documented below.

Tabs#

Tabs can be targeted with the .react-aria-Tabs CSS selector, or by overriding with a custom className. It supports the following states and render props:

Name	CSS Selector	Description
`orientation`	`[data-orientation="horizontal \| vertical"]`	The orientation of the tabs.

TabList#

A TabList can be targeted with the .react-aria-TabList CSS selector, or by overriding with a custom className. It supports the following states:

Name	CSS Selector	Description
`orientation`	`[data-orientation="horizontal \| vertical"]`	The orientation of the tab list.
`state`	`—`	State of the tab list.

Tab#

A Tab can be targeted with the .react-aria-Tab CSS selector, or by overriding with a custom className. It supports the following states and render props:

Name	CSS Selector	Description
`isHovered`	`[data-hovered]`	Whether the tab is currently hovered with a mouse.
`isPressed`	`[data-pressed]`	Whether the tab is currently in a pressed state.
`isSelected`	`[data-selected]`	Whether the tab is currently selected.
`isFocused`	`[data-focused]`	Whether the tab is currently focused.
`isFocusVisible`	`[data-focus-visible]`	Whether the tab is currently keyboard focused.
`isDisabled`	`[data-disabled]`	Whether the tab is disabled.

TabPanel#

A TabPanel can be targeted with the .react-aria-TabPanel CSS selector, or by overriding with a custom className. It supports the following states and render props:

Name	CSS Selector	Description
`isFocused`	`[data-focused]`	Whether the tab panel is currently focused.
`isFocusVisible`	`[data-focus-visible]`	Whether the tab panel is currently keyboard focused.
`isInert`	`[data-inert]`	Whether the tab panel is currently non-interactive. This occurs when the `shouldForceMount` prop is true, and the corresponding tab is not selected.
`state`	`—`	State of the tab list.

Advanced customization#

Contexts#

All React Aria Components export a corresponding context that can be used to send props to them from a parent element. This enables you to build your own compositional APIs similar to those found in React Aria Components itself. You can send any prop or ref via context that you could pass to the corresponding component. The local props and ref on the component are merged with the ones passed via context, with the local props taking precedence (following the rules documented in mergeProps).

Component	Context	Props	Ref
`Tabs`	`TabsContext`	`TabsProps`	`HTMLDivElement`

This example shows a Router component that accepts Tabs and Link elements as children. When a link is clicked, it updates the selected tab accordingly.

import type {PressEvent} from 'react-aria-components';
import {TabsContext, LinkContext} from 'react-aria-components';

function Router({children}) {
  let [selectedKey, onSelectionChange] = React.useState(null);
  let onPress = (e: PressEvent) => {
    onSelectionChange(e.target.getAttribute('data-href'));
  };

  return (
    <TabsContext.Provider value={{selectedKey, onSelectionChange}}>      <LinkContext.Provider value={{onPress}}>
        {children}
      </LinkContext.Provider>
    </TabsContext.Provider>
  );
}

import type {PressEvent} from 'react-aria-components';
import {
  LinkContext,
  TabsContext
} from 'react-aria-components';

function Router({ children }) {
  let [selectedKey, onSelectionChange] = React.useState(
    null
  );
  let onPress = (e: PressEvent) => {
    onSelectionChange(e.target.getAttribute('data-href'));
  };

  return (
    <TabsContext.Provider
      value={{ selectedKey, onSelectionChange }}
    >      <LinkContext.Provider value={{ onPress }}>
        {children}
      </LinkContext.Provider>
    </TabsContext.Provider>
  );
}

import type {PressEvent} from 'react-aria-components';
import {
  LinkContext,
  TabsContext
} from 'react-aria-components';

function Router(
  { children }
) {
  let [
    selectedKey,
    onSelectionChange
  ] = React.useState(
    null
  );
  let onPress = (
    e: PressEvent
  ) => {
    onSelectionChange(
      e.target
        .getAttribute(
          'data-href'
        )
    );
  };

  return (
    <TabsContext.Provider
      value={{
        selectedKey,
        onSelectionChange
      }}
    >      <LinkContext.Provider
        value={{
          onPress
        }}
      >
        {children}
      </LinkContext.Provider>
    </TabsContext.Provider>
  );
}

Now clicking a link rendered within a Router navigates to the linked tab.

import {Link} from 'react-aria-components';

<Router>
  <Tabs>
    <TabList aria-label="Mesozoic time periods">
      <Tab id="triassic">Triassic</Tab>
      <Tab id="jurassic">Jurassic</Tab>
      <Tab id="cretaceous">Cretaceous</Tab>
    </TabList>
    <TabPanel id="triassic">
      The Triassic ranges roughly from 252 million to 201 million years ago,
      preceding the <Link data-href="jurassic">Jurassic Period</Link>.
    </TabPanel>
    <TabPanel id="jurassic">
      The Jurassic ranges from 200 million years to 145 million years ago,
      preceding the <Link data-href="cretaceous">Cretaceous Period</Link>.
    </TabPanel>
    <TabPanel id="cretaceous">
      The Cretaceous is the longest period of the Mesozoic, spanning from 145
      million to 66 million years ago.
    </TabPanel>
  </Tabs>
</Router>

import {Link} from 'react-aria-components';

<Router>
  <Tabs>
    <TabList aria-label="Mesozoic time periods">
      <Tab id="triassic">Triassic</Tab>
      <Tab id="jurassic">Jurassic</Tab>
      <Tab id="cretaceous">Cretaceous</Tab>
    </TabList>
    <TabPanel id="triassic">
      The Triassic ranges roughly from 252 million to 201
      million years ago, preceding the{' '}
      <Link data-href="jurassic">Jurassic Period</Link>.
    </TabPanel>
    <TabPanel id="jurassic">
      The Jurassic ranges from 200 million years to 145
      million years ago, preceding the{' '}
      <Link data-href="cretaceous">
        Cretaceous Period
      </Link>.
    </TabPanel>
    <TabPanel id="cretaceous">
      The Cretaceous is the longest period of the
      Mesozoic, spanning from 145 million to 66 million
      years ago.
    </TabPanel>
  </Tabs>
</Router>

import {Link} from 'react-aria-components';

<Router>
  <Tabs>
    <TabList aria-label="Mesozoic time periods">
      <Tab id="triassic">
        Triassic
      </Tab>
      <Tab id="jurassic">
        Jurassic
      </Tab>
      <Tab id="cretaceous">
        Cretaceous
      </Tab>
    </TabList>
    <TabPanel id="triassic">
      The Triassic
      ranges roughly
      from 252 million
      to 201 million
      years ago,
      preceding the
      {' '}
      <Link data-href="jurassic">
        Jurassic Period
      </Link>.
    </TabPanel>
    <TabPanel id="jurassic">
      The Jurassic
      ranges from 200
      million years to
      145 million years
      ago, preceding
      the{' '}
      <Link data-href="cretaceous">
        Cretaceous
        Period
      </Link>.
    </TabPanel>
    <TabPanel id="cretaceous">
      The Cretaceous is
      the longest
      period of the
      Mesozoic,
      spanning from 145
      million to 66
      million years
      ago.
    </TabPanel>
  </Tabs>
</Router>

State#

Tabs provides a TabListState object to its children via TabListStateContext. This can be used to access and manipulate the tab list state.

This example shows a TabNavigation component that can be placed within Tabs to navigate to the previous or next selected tab.

import {TabListStateContext, Button} from 'react-aria-components';

function TabNavigation() {
  let state = React.useContext(TabListStateContext);  let prevKey = state?.collection.getKeyBefore(state.selectedKey);
  let nextKey = state?.collection.getKeyAfter(state.selectedKey);
  let onPrev = prevKey != null ? () => state.setSelectedKey(prevKey) : null;
  let onNext = nextKey != null ? () => state.setSelectedKey(nextKey) : null;
  return (
    <div className="button-group">
      <Button aria-label="Previous tab" onPress={onPrev}>←</Button>
      <Button aria-label="Next tab" onPress={onNext}>→</Button>
    </div>
  );
}

<Tabs>
  <div style={{display: 'flex'}}>
    <TabList aria-label="Tabs" style={{flex: 1}}>
      <Tab id="home">Home</Tab>
      <Tab id="projects">Projects</Tab>
      <Tab id="search">Search</Tab>
    </TabList>
    <TabNavigation />  </div>
  <TabPanel id="home">Home</TabPanel>
  <TabPanel id="projects">Projects</TabPanel>
  <TabPanel id="search">Search</TabPanel>
</Tabs>

import {
  Button,
  TabListStateContext
} from 'react-aria-components';

function TabNavigation() {
  let state = React.useContext(TabListStateContext);  let prevKey = state?.collection.getKeyBefore(
    state.selectedKey
  );
  let nextKey = state?.collection.getKeyAfter(
    state.selectedKey
  );
  let onPrev = prevKey != null
    ? () => state.setSelectedKey(prevKey)
    : null;
  let onNext = nextKey != null
    ? () => state.setSelectedKey(nextKey)
    : null;
  return (
    <div className="button-group">
      <Button aria-label="Previous tab" onPress={onPrev}>
        ←
      </Button>
      <Button aria-label="Next tab" onPress={onNext}>
        →
      </Button>
    </div>
  );
}

<Tabs>
  <div style={{ display: 'flex' }}>
    <TabList aria-label="Tabs" style={{ flex: 1 }}>
      <Tab id="home">Home</Tab>
      <Tab id="projects">Projects</Tab>
      <Tab id="search">Search</Tab>
    </TabList>
    <TabNavigation />  </div>
  <TabPanel id="home">Home</TabPanel>
  <TabPanel id="projects">Projects</TabPanel>
  <TabPanel id="search">Search</TabPanel>
</Tabs>

import {
  Button,
  TabListStateContext
} from 'react-aria-components';

function TabNavigation() {
  let state = React
    .useContext(
      TabListStateContext
    );  let prevKey = state
    ?.collection
    .getKeyBefore(
      state.selectedKey
    );
  let nextKey = state
    ?.collection
    .getKeyAfter(
      state.selectedKey
    );
  let onPrev =
    prevKey != null
      ? () =>
        state
          .setSelectedKey(
            prevKey
          )
      : null;
  let onNext =
    nextKey != null
      ? () =>
        state
          .setSelectedKey(
            nextKey
          )
      : null;
  return (
    <div className="button-group">
      <Button
        aria-label="Previous tab"
        onPress={onPrev}
      >
        ←
      </Button>
      <Button
        aria-label="Next tab"
        onPress={onNext}
      >
        →
      </Button>
    </div>
  );
}

<Tabs>
  <div
    style={{
      display: 'flex'
    }}
  >
    <TabList
      aria-label="Tabs"
      style={{
        flex: 1
      }}
    >
      <Tab id="home">
        Home
      </Tab>
      <Tab id="projects">
        Projects
      </Tab>
      <Tab id="search">
        Search
      </Tab>
    </TabList>
    <TabNavigation />  </div>
  <TabPanel id="home">
    Home
  </TabPanel>
  <TabPanel id="projects">
    Projects
  </TabPanel>
  <TabPanel id="search">
    Search
  </TabPanel>
</Tabs>

Hooks#

If you need to customize things even further, such as accessing internal state or customizing DOM structure, you can drop down to the lower level Hook-based API. See useTabList for more details.

A Collection renders a list of items, automatically managing caching and keys.

Name	Type	Description
`items`	`Iterable<object>`	Item objects in the collection.
`children`	`ReactNode \| ( (item: object )) => ReactNode`	The contents of the collection.
`dependencies`	`any[]`	Values that should invalidate the item cache when using dynamic collections.
`idScope`	`Key`	A scope to prepend to all child item ids to ensure they are unique.
`addIdAndValue`	`boolean`	Whether to add `id` and `value` props to all child items.

string | number

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: Href, , routerOptions: RouterOptions \| \| undefined )) => void`
`children`	`ReactNode`
`useHref`	`( (href: Href )) => string`

RouterConfig extends {href: any
} ? H : string

RouterConfig extends {routerOptions: any
} ? O : never

'horizontal' | 'vertical'

Name	Type	Description
`orientation`	`Orientation`	The orientation of the tabs.

Name	Type	Description
`orientation`	`Orientation`	The orientation of the tab list.
`state`	`TabListState<unknown>`	State of the tab list.

Properties

Name	Type	Description
`isDisabled`	`boolean`	Whether the tab list is disabled.
`selectedKey`	`Key \| null`	The key for the currently selected item.
`selectedItem`	`Node<T> \| null`	The value of the currently selected item.
`collection`	`Collection<Node<T>>`	A collection of items in the list.
`disabledKeys`	`Set<Key>`	A set of items that are disabled.
`selectionManager`	`SelectionManager`	A selection manager to read and update multiple selection state.

Methods

Method	Description
`setSelectedKey( (key: Key \| \| null )): 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 \| null`	The object value the node was created from.
`level`	`number`	The level of depth this node is at in the hierarchy.
`hasChildNodes`	`boolean`	Whether this item has children, even if not loaded yet.
`rendered`	`ReactNode`	The rendered contents of this node (e.g. JSX).
`textValue`	`string`	A string value for this node, used for features like typeahead.
`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.
`render`	`( (node: Node<any> )) => ReactElement`	A function that renders this node to a React Element in the DOM.

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

Extends: Iterable

Properties

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

Methods

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

An interface for reading and updating multiple selection state.

Properties

Name	Type	Description
`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`
`getItemProps( (key: Key )): void`

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectedKeys`	`Selection`	The currently selected keys in the collection.
`disabledKeys`	`Set<Key>`	The currently disabled keys in the collection.
`disabledBehavior`	`DisabledBehavior`	Whether `disabledKeys` applies to selection, actions, or both.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	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 \| \| null, , child?: FocusStrategy )): void`	Sets the focused key, and optionally, whether the first or last child of that key should receive focus.

'none'
  | 'single'
  | 'multiple'

'toggle' | 'replace'

'all' | Set<Key>

'selection' | 'all'

'first' | 'last'

A LayoutDelegate provides layout information for collection items.

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

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

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

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

Properties

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

Methods

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

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

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

Name	Type	Description
`isHovered`	`boolean`	Whether the tab is currently hovered with a mouse.
`isPressed`	`boolean`	Whether the tab is currently in a pressed state.
`isSelected`	`boolean`	Whether the tab is currently selected.
`isFocused`	`boolean`	Whether the tab is currently focused.
`isFocusVisible`	`boolean`	Whether the tab is currently keyboard focused.
`isDisabled`	`boolean`	Whether the tab is disabled.

Name	Type	Description
`type`	`'hoverstart' \| 'hoverend'`	The type of hover event being fired.
`pointerType`	`'mouse' \| 'pen'`	The pointer type that triggered the hover event.
`target`	`HTMLElement`	The target element of the hover event.

Name	Type	Description
`isFocused`	`boolean`	Whether the tab panel is currently focused.
`isFocusVisible`	`boolean`	Whether the tab panel is currently keyboard focused.
`isInert`	`boolean`	Whether the tab panel is currently non-interactive. This occurs when the `shouldForceMount` prop is true, and the corresponding tab is not selected.
`state`	`TabListState<unknown>`	State of the tab list.

Name	Type	Default	Description
`isDisabled`	`boolean`	—	Whether the TabList is disabled. Shows that a selection exists, but is not available in that circumstance.
`disabledKeys`	`Iterable<Key>`	—	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`selectedKey`	`Key \| null`	—	The currently selected key in the collection (controlled).
`defaultSelectedKey`	`Key`	—	The initial selected key in the collection (uncontrolled).
`onSelectionChange`	`( (key: Key )) => void`	—	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.
`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.
`id`	`string`	—	The element's unique identifier. See MDN.
`children`	`ReactNode \| ( (values: TabsRenderProps & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	—	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: TabsRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: TabsRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	—	The inline style for the element. A function may be provided to compute the style based on component state.
`slot`	`string \| null`	—	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.