Unstyled Tabs

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

Demos Components API Hooks API

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 the Tabs List and Tab Panel components so that tabs and their panels can communicate with one another.

My account page

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/TabsListUnstyled';
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, Tab components 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 the Tab and Tab Panel to take control over how these components are associated with one another.

The following demo omits the value prop from the Tab components, and also defines 0 as the defaultValue for the Tabs component, 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 Tab components will automatically add the necessary accessibility attributes.

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 Tab 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/tabs/)

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 /> 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, according 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):

TabPanelUnstyled API

Import

import TabPanelUnstyled from '@mui/base/TabPanelUnstyled';
// or
import { TabPanelUnstyled } from '@mui/base';

You can learn about the difference by reading this guide on minimizing bundle size.

Props

Props of the native component are also available.

Name	Type	Default	Description
value^*	number \| string		The value of the TabPanel. It will be shown when the Tab with the corresponding value is selected.
children	node		The content of the component.
component	elementType		The component used for the root node. Either a string to use a HTML element or a component.
slotProps	{ root?: func \| object }	{}	The props used for each slot inside the TabPanel.
slots	{ root?: elementType }	{}	The components used for each slot inside the TabPanel. Either a string to use a HTML element or a component. See Slots API below for more details.

The ref is forwarded to the root element.

TabUnstyled API

Import

import TabUnstyled from '@mui/base/TabUnstyled';
// or
import { TabUnstyled } from '@mui/base';

You can learn about the difference by reading this guide on minimizing bundle size.

Props

Props of the native component are also available.

Name	Type	Default	Description
action	func \| { current?: { focusVisible: func } }		A ref for imperative actions. It currently only supports `focusVisible()` action.
component	elementType		The component used for the root node. Either a string to use a HTML element or a component.
disabled	bool	false	If `true`, the component is disabled.
onChange	func		Callback invoked when new value is being set.
slotProps	{ root?: func \| object }	{}	The props used for each slot inside the Tab.
slots	{ root?: elementType }	{}	The components used for each slot inside the Tab. Either a string to use a HTML element or a component. See Slots API below for more details.
value	number \| string		You can provide your own value. Otherwise, we fall back to the child position index.

The ref is forwarded to the root element.

TabsListUnstyled API

Import

import TabsListUnstyled from '@mui/base/TabsListUnstyled';
// or
import { TabsListUnstyled } from '@mui/base';

You can learn about the difference by reading this guide on minimizing bundle size.

Props

Props of the native component are also available.

Name	Type	Default	Description
children	node		The content of the component.
component	elementType		The component used for the root node. Either a string to use a HTML element or a component.
slotProps	{ root?: func \| object }	{}	The props used for each slot inside the TabsList.
slots	{ root?: elementType }	{}	The components used for each slot inside the TabsList. Either a string to use a HTML element or a component. See Slots API below for more details.

The ref is forwarded to the root element.

TabsUnstyled API

Import

import TabsUnstyled from '@mui/base/TabsUnstyled';
// or
import { TabsUnstyled } from '@mui/base';

You can learn about the difference by reading this guide on minimizing bundle size.

Props

Props of the native component are also available.

Name	Type	Default	Description
children	node		The content of the component.
component	elementType		The component used for the root node. Either a string to use a HTML element or a component.
defaultValue	false \| number \| string		The default value. Use when the component is not controlled.
direction	'ltr' \| 'rtl'	'ltr'	The direction of the text.
onChange	func		Callback invoked when new value is being set.
orientation	'horizontal' \| 'vertical'	'horizontal'	The component orientation (layout flow direction).
selectionFollowsFocus	bool		If `true` the selected tab changes on focus. Otherwise it only changes on activation.
slotProps	{ root?: func \| object }	{}	The props used for each slot inside the Tabs.
slots	{ root?: elementType }	{}	The components used for each slot inside the Tabs. Either a string to use a HTML element or a component. See Slots API below for more details.
value	false \| number \| string		The value of the currently selected `Tab`. If you don't want any selected `Tab`, you can set this prop to `false`.

The ref is forwarded to the root element.

useTab API

Import

import useTab from '@mui/base/useTab';
// or
import { useTab } from '@mui/base';

You can learn about the difference by reading this guide on minimizing bundle size.

Parameters

Name	Type	Description
ref^*	React.Ref<any>
disabled	boolean
onChange	(event: React.SyntheticEvent, value: number \| string) => void	Callback invoked when new value is being set.
onClick	React.MouseEventHandler
onFocus	React.FocusEventHandler
value	number \| string	You can provide your own value. Otherwise, we fall back to the child position index.

Return value

Name	Type	Default	Description
active	boolean	false	If `true`, the component will be active.
disabled	boolean	false	If `true`, the component will be disabled.
focusVisible	boolean		If `true`, the tab's focus will be visible.
getRootProps	<TOther extends Record<string, any> = {}>(externalProps?: TOther) => UseTabRootSlotProps<TOther>		Resolver for the root slot's props.
selected	boolean		If `true`, the tab will be selected.
setFocusVisible	React.Dispatch<React.SetStateAction<boolean>>		Callback for setting the `focusVisible` param.

useTabPanel API

Import

import useTabPanel from '@mui/base/useTabPanel';
// or
import { useTabPanel } from '@mui/base';

You can learn about the difference by reading this guide on minimizing bundle size.

Parameters

Name	Type	Default	Description
value^*	number \| string		The value of the TabPanel. It will be shown when the Tab with the corresponding value is selected.

Return value

Name	Type	Default	Description
getRootProps	() => { 'aria-labelledby': string \| undefined hidden: boolean id: string \| undefined }		Resolver for the root slot's props.
hidden	boolean	false	If `true`, it indicates that the tab panel will be hidden.

useTabs API

Import

import useTabs from '@mui/base/useTabs';
// or
import { useTabs } from '@mui/base';

You can learn about the difference by reading this guide on minimizing bundle size.

Parameters

Name	Type	Default	Description
defaultValue	string \| number \| false		The default value. Use when the component is not controlled.
direction	'ltr' \| 'rtl'	'ltr'	The direction of the text.
onChange	(event: React.SyntheticEvent, value: number \| string \| boolean) => void		Callback invoked when new value is being set.
orientation	'horizontal' \| 'vertical'	'horizontal'	The component orientation (layout flow direction).
selectionFollowsFocus	boolean		If `true` the selected tab changes on focus. Otherwise it only changes on activation.
value	string \| number \| false		The value of the currently selected `Tab`. If you don't want any selected `Tab`, you can set this prop to `false`.

Return value

Name	Type	Default	Description
tabsContextValue	TabsContextValue		Returns the values to be passed to the tabs context provider.

useTabsList API

Import

import useTabsList from '@mui/base/useTabsList';
// or
import { useTabsList } from '@mui/base';

You can learn about the difference by reading this guide on minimizing bundle size.

Parameters

Name	Type	Description
ref^*	React.Ref<unknown>
aria-label	string
aria-labelledby	string
children	React.ReactNode	The content of the component.

Return value

Name	Type	Default	Description
getRootProps	<TOther extends Record<string, any> = {}>(externalProps?: TOther) => UseTabsListRootSlotProps<TOther>		Resolver for the root slot's props.
isRtl	boolean	false	If `true`, it will indicate that the text's direction in right-to-left.
orientation	'horizontal' \| 'vertical'	'horizontal'	The component orientation (layout flow direction).
processChildren	() => React.ReactElement<any, string \| React.JSXElementConstructor<any>>[] \| null \| undefined		Callback for processing the children of the tabs list. It adds the necessary attributes for correct a11y and navigation.
value	string \| number \| false		The value of the currently selected `Tab`.