Navigation
Tabs
Tabs let users switch between views within the same context.
Interactive demo
This demo lets you preview the tabs component, its variations and configuration options.
Stories of our Times | One remarkable story, told in depth, each day. Our daily news podcast takes you to the heart of the stories that matter, with exclusive access and reporting. Published for the start of your day and hosted by Manveen Rana and David Aaronovitch.
Anatomy
Tabs contain four required elements and one optional element.
Options
Tabs have options for different use cases:
Size
Tabs come in small, medium and large. Tab labels, icons and the tab container change size. Tabs match the heights of the three button sizes, so they align when used together.
Icons (leading & trailing)
Add an icon to a tab item. Icons can be positioned either before (leading) or after (trailing) the tab label.
Label
Add labels to tab items. A label can give more context to the content that will be displayed when the user selects a tab.
Orientation
Display tabs horizontally or vertically.
Indicator position
Display the tabs indicator on the bottom of the tab for the horizontal orientation and left or right of the tab for the vertical orientation.
Indicator size
Change the size of the tab indicator to give more or less prominence, using either: full-width of the tab, fixed-width/fixed-height (based on orientation) or a percentage of the tab height/width (based on orientation).
Indicator weight
Customise the weight of the tab indicator to give more or less affordance.
Track weight
Customise the weight of the tab track to give more or less affordance.
Dividers
Add dividers between tab items. Dividers match the width or height (depending on orientation) of the tab items.
Distribution
Start Aligns the tab items to the left of the content area for horizontal orientation (default) and to the top for vertical orientation. The width of the tab group is defined by the width of its children.
Grow Spreads all tab items across the content area, filling the entire available width or height, depending on the orientation. The width of each tab item is defined by its content.
Equal Spaces each tab item across the content area equally, regardless of the width or height of its children.
Alignment
Start Aligns the tab item label and icons to the left.
Center Centres the tab item label and icons.
End Aligns the tab item label and icons to the right.
The default alignment depends on the orientation. When tabs are vertical it’s Start and when tabs are horizontal it’s Center.
Size
Tabs come in small, medium and large. Tab labels, icons and the tab container change size. Tabs match the heights of the three button sizes, so they align when used together.
Icons (leading & trailing)
Add an icon to a tab item. Icons can be positioned either before (leading) or after (trailing) the tab label.
Label
Add labels to tab items. A label can give more context to the content that will be displayed when the user selects a tab.
Orientation
Display tabs horizontally or vertically.
Indicator position
Display the tabs indicator on the bottom of the tab for the horizontal orientation and left or right of the tab for the vertical orientation.
Indicator size
Change the size of the tab indicator to give more or less prominence, using either: full-width of the tab, fixed-width/fixed-height (based on orientation) or a percentage of the tab height/width (based on orientation).
Indicator weight
Customise the weight of the tab indicator to give more or less affordance.
Track weight
Customise the weight of the tab track to give more or less affordance.
Dividers
Add dividers between tab items. Dividers match the width or height (depending on orientation) of the tab items.
Distribution
Start Aligns the tab items to the left of the content area for horizontal orientation (default) and to the top for vertical orientation. The width of the tab group is defined by the width of its children.
Grow Spreads all tab items across the content area, filling the entire available width or height, depending on the orientation. The width of each tab item is defined by its content.
Equal Spaces each tab item across the content area equally, regardless of the width or height of its children.
Alignment
Start Aligns the tab item label and icons to the left.
Center Centres the tab item label and icons.
End Aligns the tab item label and icons to the right.
The default alignment depends on the orientation. When tabs are vertical it’s Start and when tabs are horizontal it’s Center.
States
Tabs have the following states. By default, tabs have one tab item in a selected state.
Base
The default style before the user interacts with the tab item.
Hover
The tab item changes style to let the user know it’s interactive.
Active
The tab item changes style to let the user know they’ve interacted with it.
Selected
The tab item changes style to let the user know they’ve selected it.
Disabled
Communicates that a tab item exists, but isn’t available in that scenario. When the user hovers over a tab item in a disabled state, the cursor shows as ‘not allowed’.
Disabled tab items maintain layout consistency and communicate that a tab item may become available if another condition is met.
Focus
Communicates that a tab item exists, but isn’t available in that scenario. When the user hovers over a tab item in a disabled state, the cursor shows as ‘not allowed’.
Behaviours
Here’s how tabs behave:
Animation
When the user selects a tab item, the indicator slides along the track of the tabs to the newly selected tab item. At the time of selection, the tabs content changes immediately.
Selected
The user can only select one tab item at a time. This property changes an individual tab item’s selected state.
Tabs overflow
When there are too many tabs to fit horizontally across the viewport, a scroll component is applied. On desktop, the controls (buttons) are rendered on the scroll.
Label overflow wrap
When the label in a tab item is too long for the available horizontal space, it wraps to form another line.
Animation
When the user selects a tab item, the indicator slides along the track of the tabs to the newly selected tab item. At the time of selection, the tabs content changes immediately.
Selected
The user can only select one tab item at a time. This property changes an individual tab item’s selected state.
Tabs overflow
When there are too many tabs to fit horizontally across the viewport, a scroll component is applied. On desktop, the controls (buttons) are rendered on the scroll.
Label overflow wrap
When the label in a tab item is too long for the available horizontal space, it wraps to form another line.
Usage
Here’s how and when to use tabs:
Do use tabs to switch between views
Use tabs to let users alternate between views within the same context.
Don’t truncate tab labels
Tab item labels shouldn’t be truncated. Keep them short, clear and fully visible.
Do use when there are two or more content views
Use tabs when users have two or more content views to choose from.
Don’t nest tabs
Avoid nesting tabs as this can cause usability issues. Consider an alternative component (e.g. accordion) or rethink the page structure.
Do use sentence case for labels
Tab labels should be written in sentence case to help with scannability and legibility.
Don’t use more than 5 tabs
Avoid using tabs when there are five or more content views. Consider an alternative component (e.g. select) to reduce the user’s cognitive load.
Do keep tabs in view of the content
Tabs should remain in view of the content. If the content is too large to display with the tabs in the same viewport, make the tabs fixed (sticky).
Don’t mix tabs with and without icons
Avoid mixing tab items that include an icon with those that don’t include an icon. This helps ensure they have equal importance.
Do use vertical orientation when space is limited
Use the vertical orientation when there are more than five tabs and horizontal space is limited.
Don’t use tabs to navigate to different pages
Avoid using tabs to navigate to different pages and anchoring to different sections on a page. Use a navigation component (e.g. link) instead.
Accessibility considerations
Tabs implement the latest WAI-ARIA Tabs specifications.
| Order | Element | Role |
|---|---|---|
1 | tab | Focusses to the first tab item in a tab list. |
2 | tabPanel | Focusses to the tab panel. |
| Command | Description |
|---|---|
Tab | When focus is outside the tab list, moves focus to the active tab. If focus is on the active tab, moves focus to the next element in the keyboard focus tabs associated tab panel |
Rtn | Activates the tab if it wasn’t activated automatically on focus |
Left | Focusses and activates the previous tab in the tab list when the orientation of the tabs is horizontal. If the current tab is the first tab in the tab list it activates the last tab |
Right | Focusses and activates the next tab in the tab list when the orientation of the tabs is horizontal. If the current tab is the last tab in the tab list it activates the first tab |
Up | Focusses and activates the previous tab in the tab list when the orientation of the tabs is vertical. If the current tab is the first tab in the tab list it activates the last tab |
Down | Focusses and activates the next tab in the tab list when the orientation of the tabs is vertical. If the current tab is the last tab in the tab list it activates the first tab |
Home | Focusses and activates the first tab in the tab list |
End | Focusses and activates the last tab in the tab list |
| Element | Attribute | Value | Description | User supplied |
|---|---|---|---|---|
| tab | arialabel | Defines a string that labels the action that will be performed when the user interacts with a tab item (e.g. ariaLabel="view component overrides”) | ||
| tab | aria-selected | “true” or “false” | Indicates the currently selected tab | |
| tab | aria-controls | auto-generated | Maintains a reference from the tab to the associated panel | |
| tab | aria-hidden | “true” | Hides the tab bar indicator from screen readers | |
| tab | aria-labelledby | auto-generated | Maintains a reference from the tab to the associated panel | |
| tab | role | “tabpanel” | Indicates an interactive element inside a tab group that, when activated, displays its associated tab panel | |
| tab | aria-orientation | “horizontal” or “vertical” | Describes the orientation of the tabs |
By default, aria-label will match the tab text label. Where a tab item text label is not visible on the screen (i.e. if there’s only an icon in a tab item) a string should be passed to the title prop on the icon.
SEO considerations
Ensure icons have alt text applied.
API
Tabs have a range of props for different use cases, and a range of predefined elements and attributes that can be overridden to define their appearance.
| Name | Type | Default | Description | Required |
|---|---|---|---|---|
| children | React.ReactNode | An array of tab components | ||
| vertical | boolean | false | If ‘true’, changes the orientation to vertical | |
| distribution | start | grow | equal | start | Defines the distribution of the tabs | |
| align | start | end | center | start | Defines the alignment of the tabs | |
| divider | boolean | false | If ‘true’, renders a divider component between tab items in a tab list | |
| initialSelectedIndex | number | 0 | Defines the index of the initially selected Tab item (uncontrolled). | |
| selectedIndex | number | Defines the index of the selected tab item. When changing this value, tab item state is updated (controlled) | ||
| onChange | (selectedIndex:number):void | Callback fired when the selected tab changes |
To support resizing of the selected tab indicator this component uses the ResizeObserver API this is not supported in Internet explorer, if you require support we suggest you add a pollyfill to your application.
A tab has a range of props for different use cases, and a range of predefined elements and attributes that can be overridden to define its appearance.
| Name | Type | Default | Description | Required |
|---|---|---|---|---|
| children | React.ReactNode | Content rendered inside the tab panel | ||
| label | React.ReactNode | Label of the tab item | ||
| ariaLabel | string | label | Defines the aria-label attribute of the tab item | |
| disabled | boolean | false | If ‘true’, renders a tab in a disabled state | |
| autoFocus | boolean | false | If ‘true’, this tab will be auto-focussed. Only one item on the page can be auto-focussed | |
| dataTestId | string | tab | Defines the data-testid attribute of the tab item |