Unstyled tabs

Tabs are UI elements for organizing and navigating between groups of related content.

Introduction

Tabs are implemented using a collection of related components:

TabUnstyled - the tab element itself. Clicking on a tab displays its corresponding panel.
TabsListUnstyled - the container that houses the tabs. Responsible for handling focus and keyboard navigation between tabs.
TabPanelUnstyled - the card that hosts the content associated with a tab.
TabsUnstyled - the top-level component that wraps TabsListUnstyled and TabPanelUnstyled so that tabs and their panels can communicate with one another.

Components

Usage

After installation, you can start building with this component collection using the following basic elements:

import TabUnstyled from '@mui/base/TabUnstyled';
import TabsListUnstyled from '@mui/base/TabUnstyled';
import TabPanelUnstyled from '@mui/base/TabPanelUnstyled';
import TabsUnstyled from '@mui/base/TabsUnstyled';

export default function MyApp() {
  return (
    <TabsUnstyled>
      <TabsListUnstyled>
        <TabUnstyled>{/* tab one */}</TabUnstyled>
        <TabUnstyled>{/* tab two */}</TabUnstyled>
      </TabsListUnstyled>
      <TabPanelUnstyled>{/* panel one */}</TabPanelUnstyled>
      <TabPanelUnstyled>{/* panel two */}</TabPanelUnstyled>
    </TabsUnstyled>
  );
}

Basics

By default, tabs and their corresponding panels are zero-indexed (i.e. the first tab has a value of 0, then 1, 2, etc.). Clicking on a given tab opens the panel with the same value, which corresponds to the order in which each component is nested within its container.

Though not required, you can add the value prop to TabUnstyled and TabPanelUnstyled to take control over how these components are associated with one another.

The following demo omits the value prop from the TabUnstyled components, and also defines 0 as the defaultValue for TabsUnstyled, which sets the first tab and panel as the defaults:

First page

<TabsUnstyled defaultValue={0}>
  <TabsListUnstyled>
    <TabUnstyled>One</TabUnstyled>
    <TabUnstyled>Two</TabUnstyled>
    <TabUnstyled>Three</TabUnstyled>
  </TabsListUnstyled>
  <TabPanelUnstyled value={0}>First page</TabPanelUnstyled>
  <TabPanelUnstyled value={1}>Second page</TabPanelUnstyled>
  <TabPanelUnstyled value={2}>Third page</TabPanelUnstyled>
</TabsUnstyled>

<TabsUnstyled defaultValue={0}>
  <TabsListUnstyled>
    <TabUnstyled>One</TabUnstyled>
    <TabUnstyled>Two</TabUnstyled>
    <TabUnstyled>Three</TabUnstyled>
  </TabsListUnstyled>
  <TabPanelUnstyled value={0}>First page</TabPanelUnstyled>
  <TabPanelUnstyled value={1}>Second page</TabPanelUnstyled>
  <TabPanelUnstyled value={2}>Third page</TabPanelUnstyled>
</TabsUnstyled>

Press Enter to start editing

The next demo shows how to apply custom styles to a set of tabs:

First page

<TabsUnstyled defaultValue={0}>
  <TabsList>
    <Tab>One</Tab>
    <Tab>Two</Tab>
    <Tab>Three</Tab>
  </TabsList>
  <TabPanel value={0}>First page</TabPanel>
  <TabPanel value={1}>Second page</TabPanel>
  <TabPanel value={2}>Third page</TabPanel>
</TabsUnstyled>

<TabsUnstyled defaultValue={0}>
  <TabsList>
    <Tab>One</Tab>
    <Tab>Two</Tab>
    <Tab>Three</Tab>
  </TabsList>
  <TabPanel value={0}>First page</TabPanel>
  <TabPanel value={1}>Second page</TabPanel>
  <TabPanel value={2}>Third page</TabPanel>
</TabsUnstyled>

Press Enter to start editing

Anatomy

The tab components are each composed of a root slot with no interior slots:

<div class="TabsUnstyled-root">
  <div class="TabsListUnstyled-root">
    <button class="TabUnstyled-root">First tab</button>
    <button class="TabUnstyled-root">Second tab</button>
    <button class="TabUnstyled-root">Third tab</button>
  </div>
  <div class="TabPanelUnstyled-root">First panel</div>
  <div class="TabPanelUnstyled-root">Second panel</div>
  <div class="TabPanelUnstyled-root">Third panel</div>
</div>

Slot props

Use the component prop to override the root slot with a custom element:

<TabUnstyled component="span" />

If you provide a non-interactive element such as a <span>, the TabUnstyled component will automatically add the necessary accessibility attributes.

Use the components prop to override any interior slots in addition to the root:

<TabUnstyled components={{ Root: 'span' }} />

Use the componentsProps prop to pass custom props to internal slots. The following code snippet applies a CSS class called my-tab-list to the root slot:

<TabListUnstyled componentsProps={{ root: { className: 'my-tab-list' } }} />

Customization

Third-party routing library

A common use case for tabs is to implement client-side navigation that doesn't require an HTTP round-trip to the server.

The TabUnstyled component provides the component prop to handle this use case—see the Material UI documentation on routing for more details.

Accessibility

(WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/)

The following steps are necessary to make the tab component suite accessible to assistive technology:

Label TabsUnstyled with aria-label or aria-labelledby.
Connect each TabUnstyled component to its corresponding TabPanelUnstyled by setting the correct id, aria-controls and aria-labelledby.

The demos below illustrate the proper use of ARIA labels.

By default, when using keyboard navigation, the tab components open via manual activation—that is, the next panel is displayed only after the user activates the tab with either Space, Enter, or a mouse click.

This is the preferable behavior for tabs in most cases, acccording to the WAI-ARIA authoring practices.

Alternatively, you can set the panels to be displayed automatically when their corresponding tabs are in focus—this behavior of the selection following the focus is known as automatic activation.

To enable automatic activation, pass the selectionFollowsFocus prop to the TabsUnstyled component:

/* Tabs where selection follows focus */
<TabsUnstyled selectionFollowsFocus />

The following demo pair illustrates the difference between manual and automatic activation. Move the focus to a tab in either demo and navigate with the arrow keys to observe the difference:

Selection following focus:

Selection independent of focus (default behavior):

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.