---
title: Tabs
description: Tabs organize content into multiple sections and allow users to navigate between them
thumbnail:
  image: /previews/components/core/tabs.jpeg
  video: /previews/components/core/tabs.mp4
links:
  - label: Aria docs
    href: https://react-spectrum.adobe.com/react-aria/Tabs.html
  - label: Aria API Reference
    href: https://react-spectrum.adobe.com/react-aria/Tabs.html#props
  - label: Report an issue
    href: https://github.com/mehdibha/dotUI/issues/new/choose
  - label: Edit this page
    href: https://github.com/mehdibha/dotUI/tree/main/content/components/navigation/tabs.mdx?plain=1
---

<ComponentPreview
  name="core/tabs-basic"
  preview={`<Tabs>
    <TabList>
      <Tab id="overview">Overview</Tab>
      <Tab id="usage">Usage</Tab>
      <Tab id="settings">Settings</Tab>
    </TabList>
    <TabPanel id="overview"> You can view all your projects here. </TabPanel>
    <TabPanel id="usage"> You can view your usage here. </TabPanel>
    <TabPanel id="settings"> You can view your settings here. </TabPanel>
  </Tabs>`}
/>

## Installation

<Tabs items={["CLI", "Manual"]}>
  <Tab value="CLI">
  
  ```package-install
npx dotui-cli@latest add tabs
```

  </Tab>
  <Tab value="manual">
  
    <Steps>
      <Step>Install the following dependencies:</Step>

    ```package-install
    react-aria-components
    ```

      <Step>Copy and paste the following code into your project.</Step>
      <ComponentSource name="core/tabs" />
      <Step>Update the import paths to match your project setup.</Step>
    </Steps>

  </Tab>
</Tabs>

## Usage

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

- The content under the set of tabs should be related and form a coherent unit.

## Options

### Orientation

Use the `orientation` prop to set the orientation of the tabs.

<ComponentPreview
  name="core/tabs-vertical"
  preview={`<Tabs orientation="vertical">
    <TabList>
      <Tab id="overview">Overview</Tab>
      <Tab id="usage">Usage</Tab>
      <Tab id="settings">Settings</Tab>
    </TabList>
    <TabPanel id="overview">You can view all your projects here. </TabPanel>
    <TabPanel id="usage"> You can view your usage here. </TabPanel>
    <TabPanel id="settings"> You can view your settings here. </TabPanel>
  </Tabs>`}
/>

### Disabled

Use the `isDisabled` prop to disable the tabs.

<ComponentPreview
  name="core/tabs-disabled"
  preview={`<Tabs isDisabled>
    <TabList>
      <Tab id="overview">Overview</Tab>
      <Tab id="usage">Usage</Tab>
      <Tab id="settings">Settings</Tab>
    </TabList>
    <TabPanel id="overview"> You can view all your projects here. </TabPanel>
    <TabPanel id="usage"> You can view your usage here. </TabPanel>
    <TabPanel id="settings"> You can view your settings here. </TabPanel>
  </Tabs>`}
/>

An individual Tab can also be disabled with the `isDisabled` prop.

<ComponentPreview
  name="core/tabs-disabled-item"
  preview={`<Tabs>
    <TabList>
      <Tab id="overview">Overview</Tab>
      <Tab id="usage">Usage</Tab>
      <Tab id="settings" isDisabled>
        Settings
      </Tab>
    </TabList>
    <TabPanel id="overview"> You can view all your projects here. </TabPanel>
    <TabPanel id="usage"> You can view your usage here. </TabPanel>
    <TabPanel id="settings"> You can view your settings here. </TabPanel>
  </Tabs>`}
/>

### Keyboard activation

Prevent keyboard activation of tabs by setting `keyboardActivation` prop to `'manual'`.

<ComponentPreview
  name="core/tabs-keyboard-activation"
  preview={`<Tabs keyboardActivation="manual">
    <TabList>
      <Tab id="overview">Overview</Tab>
      <Tab id="usage">Usage</Tab>
      <Tab id="settings">Settings</Tab>
    </TabList>
    <TabPanel id="overview"> You can view all your projects here. </TabPanel>
    <TabPanel id="usage"> You can view your usage here. </TabPanel>
    <TabPanel id="settings"> You can view your settings here. </TabPanel>
  </Tabs>`}
/>

## Controlled

Use the `selectedKey` and `onSelectionChange` props to control the selected tab.

<ComponentPreview
  name="core/tabs-controlled"
  preview={`const [selectedTab, setSelectedTab] = React.useState<Key>("overview");
  return (
    <Tabs selectedKey={selectedTab} onSelectionChange={setSelectedTab}>
      <TabList>
        <Tab id="overview">Overview</Tab>
        <Tab id="usage">Usage</Tab>
        <Tab id="settings">Settings</Tab>
      </TabList>
      <TabPanel id="overview"> You can view all your projects here. </TabPanel>
      <TabPanel id="usage"> You can view your usage here. </TabPanel>
      <TabPanel id="settings"> You can view your settings here. </TabPanel>
    </Tabs>
  )`}
/>

## API Reference

### Tabs

| Prop                 | 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`        | `'horizontal' \| 'vertical'`                                                                      | `'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`                                                                                          | -             | The CSS className for the element.                                                                          |
| `style`              | `CSSProperties \| (values: TabsRenderProps & {defaultStyle: CSSProperties}) => CSSProperties`     | -             | The inline style for the element. A function may be provided to compute the style based on component state. |

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

| Data attribute                                | Description                  |
| --------------------------------------------- | ---------------------------- |
| `[data-orientation="horizontal \| vertical"]` | The orientation of the tabs. |

### TabList

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

| Data attribute                                | Description                  |
| --------------------------------------------- | ---------------------------- |
| `[data-orientation="horizontal \| vertical"]` | The orientation of the tabs. |

### Tab

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

| Data attribute         | Description                                                 |
| ---------------------- | ----------------------------------------------------------- |
| `[data-hovered]`       | Whether the tab is currently hovered with a mouse.          |
| `[data-pressed]`       | Whether the tab is currently in a pressed state.            |
| `[data-selected]`      | Whether the tab is currently selected.                      |
| `[data-focused]`       | Whether the tab is focused, either via a mouse or keyboard. |
| `[data-focus-visible]` | Whether the tab is keyboard focused.                        |
| `[data-disabled]`      | Whether the tab is disabled.                                |

### TabPanel

| Prop               | 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`                                                                                              | -       | The CSS className for the element.                                                                                                                                                                                      |
| `style`            | `CSSProperties \| (values: TabPanelRenderProps & {defaultStyle: CSSProperties}) => CSSProperties`     | -       | The inline style for the element. A function may be provided to compute the style based on component state.                                                                                                             |

| Data attribute         | Description                                                                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[data-focused]`       | Whether the tab panel is focused, either via a mouse or keyboard.                                                                                  |
| `[data-focus-visible]` | Whether the tab panel is keyboard focused.                                                                                                         |
| `[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. |

## Accessibility

### Keyboard interactions

| Key                      | Description                                                                                                                                                                         |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Tab`                    | Moves focus into the tabs component and places focus on the selected tab item. If the tabs component is already in focus, moves focus to the next element in the page tab sequence. |
| `ArrowRight` `ArrowDown` | Moves focus to the next tab item. If focus is on the last tab item, moves focus to the first tab item.                                                                              |
| `ArrowLeft` `ArrowUp`    | Moves focus to the previous tab item. If focus is on the first tab item, moves focus to the last tab item.                                                                          |
| `Space` `Enter`          | Activates the tab item in focus.                                                                                                                                                    |
