Tabs

Tabs make it easy to explore and switch between different views.

Introduction

Joy UI provides four tabs-related components:

• Tabs: A context provider that synchronizes the selected Tab with the corresponding TabPanel.
• TabList: A container that consists of Tab items.
• Tab: A button to toggle a selected tab.
• TabPanel: A pane that displays on the screen when its value matches with the selected tab.

Component

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

import Tabs from '@mui/joy/Tabs';
import TabList from '@mui/joy/TabList';
import Tab from '@mui/joy/Tab';

export default function MyApp() {
  return (
    <Tabs defaultValue={1}>
      <TabList>
        <Tab value={1}>Tab A</Tab>
        <Tab value={2}>Tab B</Tab>
        <Tab value={3}>Tab C</Tab>
      </TabList>
    </Tabs>
  );
}

Basic usage

The tabs structure follows WAI ARIA design pattern. To target the initially selected tab, specify the value prop to the TabPanel and use Tabs's defaultValue.

Variants

Both TabList and Tab accept global variant values, so you can mix and match to get the desired result.

Disabled tab

To disable a tab, use the disabled prop on the Tab component.

Vertical

To set the tabs orientation to vertical, use the orientation="vertical" on the Tabs component. Keyboard navigation (e.g. arrow keys) will adapt automatically to the used orientation.

Placement

To change the placement, you should provide the value of top, bottom, left or right.

This prop can be applied on the TabList component to change the underlinePlacement as in the example:

Or, it can be applied on the Tab component to change the indicatorPlacement:

The flex direction of the Tabs component will need to be changed based on each placement.

Sticky

For long content, you can use the sticky="top" prop on the TabList component to keep the tabs visible while scrolling.

To stick the TabList at the bottom, use sticky="bottom" and render the TabList at the end of the Tabs component.

Tab flex

Use the tabFlex prop on the TabList component to make the Tab elements fill the available space as shown in the example below.

The first demo, tabFlex={1}, the Tab elements will fill the available space equally.

The second demo, tabFlex="auto, the Tab elements will fill the available space equally, but the width of each Tab element will be based on the content.

Icon

Since TabList uses the same style as the List component, you can use the icon directly as a child or use ListItemDecorator with a text.

Accessibility

For ensuring proper accessibility, it's recommended by ARIA Authoring Practices Guide to associate a label to the Tabs component. To do that, there are two options:

Option one

Render a text element with an id and provide aria-labelledby="$is"to the Tabs component.

<Typography id="tabs-accessibility-label">Meaningful label</Typography>
<Tabs aria-labelledby="tabs-accessibility-label">...</Tabs>

Option two

When not displaying a text element on the screen, use aria-label directly on the Tabs component. Screen readers will then properly announce the label.

<Tabs aria-label="Meaningful label">...</Tabs>

CSS variables playground

Play around with all the CSS variables available in the slider component to see how the design changes.

You can use those to customize the component on both the sx prop and the theme.

Common examples

Segmented controls

To mimic the iOS segmented controls, add the border-radius to the sx prop of the TabList and set the selected Tab's background to background.surface.

Browser tabs

In this example, the Tab's variant is set to outlined and the indicator is moved to the top via indicatorPlacement="top". The borders of the Tab are set to transparent based on the selected state.

Pricing tabs

This example removes the background of the selected Tab by targeting [aria-selected="true"] on the sx prop.

With counter chips

To render tab items at the center of the TabList, use justifyContent: 'center' on the sx prop of the TabList and set flex: initial to each of the Tab to override the default flex-grow.

Mobile bottom navigation

In this example, each Tab's is applied with one of the theme's color palette when it is selected.

Unstyled

API

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

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