Tabs

Tabs group similar content within sub-views of a page.

Examples

Default tabs

A <Tabs> component contains multiple <Tab> components that may be used to navigate between sets of content within a page.

You can adjust a tab in the following ways:

  • To label a tab with text, pass a <TabTitleText> component into the title property of a <Tab>.
  • To disable a tab, use the isDisabled property. Tabs using isDisabled are not perceivable or operable by users navigating via assistive technologies.
  • To disable a tab, but keep it perceivable to assistive technology users, use the isAriaDisabled property. If a disabled tab has a tooltip, use this property instead of isDisabled.
  • To add a tooltip to an aria-disabled tab, use the tooltip property.

Tabs can be styled as 'default' or 'boxed':

  • Default tabs do not have any borders and use a bottom line to distinguish between a selected tab, a hovered tab, and an inactive tab.
  • Boxed tabs are outlined to emphasize the area that a tab spans. To preview boxed tabs in the following examples, select the 'isBox' checkbox, which sets the isBox property to true.
Users

Boxed secondary tabs

To change the background color of boxed tabs or the tab content, use the variant property.

Toggle the tab color by selecting the 'Tabs secondary variant' checkbox in the following example.

Users

Vertical tabs

Vertical tabs are placed on the left-hand side of a page or container and may appear in both 'default' and 'boxed' tab variations.

To style tabs vertically, use the isVertical property.

Users

Vertical expandable tabs

Vertical tabs can be made expandable to save space. Users can select the caret to expand a menu and switch between tabs.

Expandable tabs can be enabled at different breakpoints. The following example passes expandable={{ default: 'expandable', md: 'nonExpandable', lg: 'expandable' }} into the <Tabs> component.

To flag vertical tabs when they're expanded, use the isExpanded property.

Users

Vertical expandable uncontrolled

To flag the default expanded state for uncontrolled tabs, use the defaultIsExpanded property.

Users

Default overflow tabs

By default, overflow is applied when there are too many tabs for the width of the container they are in. This overflow can be navigated by side-scrolling within the tabs section, or by selecting the left and right arrows.

Users

Horizontal overflow tabs

Horizontal overflow can be used instead of the default application. To navigate horizontal overflow tabs users can select the last tab, labeled “more”, to see the overflowed content.

To enable horizontal overflow, use the isOverflowHorizontal property.

In the following example, select the 'Show overflowing tab count' checkbox to add a count of overflow items to the final “more” tab.

Users

With tooltip react ref

When using a React ref to link a tooltip to a tab component via the reference property, you should avoid manually passing in a value of "off" to the aria-live property. Doing so may cause the tooltip to become less accessible to assistive technologies.

The tooltip should also have the id property passed in. The value of id should be passed into the tab's aria-describedby property. This ensures a tooltip used with a React ref will be announced by the JAWS and NVDA screen readers.

Users

Uncontrolled tabs

To allow the <Tabs> component to manage setting the active tab and displaying correct content itself, use uncontrolled tabs, as shown in the following example.

Users

With adjusted inset

To adjust the inset of tabs and visually separate them more, use the inset property. You can set the inset to "insetNone", "insetSm", "insetMd", "insetLg", "insetXl", or "inset2xl" at "default", "sm", "md", "lg, "xl, and "2xl" breakpoints.

Users

With page insets

To adjust the left padding of tabs, use the usePageInsets property. This property aligns the tabs padding with the default padding of the page section, which makes it easier to align tabs with page section content.

Users

With icons and text

You can render different content in the title property of a tab to add icons and text.

To add an icon to a tab, pass a <TabTitleIcon> component that contains the icon of your choice into the title. To use an icon alongside styled text, keep the text in the <TabTitleText> component.

Users

Subtabs

Use subtabs within other components, like modals. Subtabs have less visually prominent styling.

To apply subtab styling to tabs, use the isSubtab property.

Filled tabs with icons

To allow tabs to fill the available width of the page section, use the isFilled property.

Users

Tabs linked to nav elements

To let tabs link to nav elements, pass {TabsComponent.nav} into the component property.

Nav tabs should use the href property to link the tab to the URL of another page or page section. A tab with an href will render as an <a> instead of a <button>.

Users

Subtabs linked to nav elements

Subtabs can also link to nav elements.

With separate content

If a <TabContent> component is defined outside of a <Tabs> component, use the tabContentRef and tabContentId properties

Tab 1 section

With tab content with body and padding

To add a content body to a <TabContent> component, pass a <TabContentBody>. To add padding to the body section, use the hasPadding property.

Tab 1 section with body and padding

Children mounting on click

To mount tab children (add to the DOM) when a tab is clicked, use the mountOnEnter property.

Note that this property does not create the tab children until the tab is clicked, so they are not preloaded into the DOM.

Tab 1 section

Unmounting invisible children

To unmount tab children (remove from the DOM) when they are no longer visible, use the unmountOnExit property.

Tab 1 section

Toggled tab content

You may control tabs from outside of the tabs component. For example, select the "Hide tab 2" button below to make "Tab item 2" invisible.

The tab its content should only be mounted when the tab is visible.


Tab 1 section

Dynamic tabs

To enable closeable tabs, pass the onClose property to the <Tabs> component. To enable a button that adds new tabs, pass the onAdd property to <Tabs>.

Terminal 1

With help action popover

You may add a help action to a tab to provide users with additional context in a popover.

To render an action beside the tab content, use the actions property of a <Tab>. Pass a popover and a <TabsAction> component into the actions property.

Users

With help and close actions

To add multiple actions to a tab, create a <TabAction> component for each action.

The following example passes in both help popover and close actions.

Terminal 1

Props

Tabs

*required
NameTypeDefaultDescription
childrenrequiredTabsChild | TabsChild[]Content rendered inside the tabs component. Only `Tab` components or expressions resulting in a falsy value are allowed here.
activeKeynumber | string0The index of the active tab
addButtonAriaLabelstringAria-label for the add button
aria-labelstringProvides an accessible label for the tabs. Labels should be unique for each set of tabs that are present on a page. When component is set to nav, this prop should be defined to differentiate the tabs from other navigation regions on the page.
backScrollAriaLabelstring'Scroll back'Aria-label for the back scroll button
classNamestringAdditional classes added to the tabs
component'div' | 'nav'TabsComponent.divDetermines what tag is used around the tabs. Use "nav" to define the tabs inside a navigation region
defaultActiveKeynumber | stringThe index of the default active tab. Set this for uncontrolled Tabs
defaultIsExpandedbooleanFlag indicating the default expanded state for uncontrolled expand/collapse of
expandable{ default?: 'expandable' | 'nonExpandable'; sm?: 'expandable' | 'nonExpandable'; md?: 'expandable' | 'nonExpandable'; lg?: 'expandable' | 'nonExpandable'; xl?: 'expandable' | 'nonExpandable'; '2xl'?: 'expandable' | 'nonExpandable'; }Enable expandable vertical tabs at various breakpoints. (isVertical should be set to true for this to work)
forwardScrollAriaLabelstring'Scroll forward'Aria-label for the forward scroll button
hasNoBorderBottombooleanfalseDisables border bottom tab styling on tabs. Defaults to false. To remove the bottom border, set this prop to true.
idstringUniquely identifies the tabs
inset{ default?: 'insetNone' | 'insetSm' | 'insetMd' | 'insetLg' | 'insetXl' | 'inset2xl'; sm?: 'insetNone' | 'insetSm' | 'insetMd' | 'insetLg' | 'insetXl' | 'inset2xl'; md?: 'insetNone' | 'insetSm' | 'insetMd' | 'insetLg' | 'insetXl' | 'inset2xl'; lg?: 'insetNone' | 'insetSm' | 'insetMd' | 'insetLg' | 'insetXl' | 'inset2xl'; xl?: 'insetNone' | 'insetSm' | 'insetMd' | 'insetLg' | 'insetXl' | 'inset2xl'; '2xl'?: 'insetNone' | 'insetSm' | 'insetMd' | 'insetLg' | 'insetXl' | 'inset2xl'; }Insets at various breakpoints.
isBoxbooleanfalseEnables box styling to the tab component
isExpandedbooleanFlag to indicate if the vertical tabs are expanded
isFilledbooleanfalseEnables the filled tab list layout
isOverflowHorizontalboolean | HorizontalOverflowObjectFlag which places overflowing tabs into a menu triggered by the last tab. Additionally an object can be passed with custom settings for the overflow tab.
isSubtabbooleanfalseEnables subtab tab styling
isVerticalbooleanfalseEnables vertical tab styling
Deprecated: leftScrollAriaLabelstring'Scroll left'Please use backScrollAriaLabel. Aria-label for the left scroll button
mountOnEnterbooleanfalseWaits until the first "enter" transition to mount tab children (add them to the DOM)
onAdd(event: React.MouseEvent<HTMLElement, MouseEvent>) => voidCallback for the add button. Passing this property inserts the add button
onClose(event: React.MouseEvent<HTMLElement, MouseEvent>, eventKey: number | string) => voidCallback to handle tab closing and adds a basic close button to all tabs. This is overridden by the tab actions property.
onSelect(event: React.MouseEvent<HTMLElement, MouseEvent>, eventKey: number | string) => void() => undefined as anyCallback to handle tab selection
onToggle(event: React.MouseEvent, isExpanded: boolean) => void(_event: React.MouseEvent, _isExpanded: boolean): void => undefinedCallback function to toggle the expandable tabs.
ouiaIdnumber | stringValue to overwrite the randomly generated data-ouia-component-id.
ouiaSafebooleantrueSet the value of data-ouia-safe. Only set to true when the component is in a static state, i.e. no animations are occurring. At all other times, this value must be false.
Deprecated: rightScrollAriaLabelstring'Scroll right'Please use forwardScrollAriaLabel. Aria-label for the right scroll button
toggleAriaLabelstringAria-label for the expandable toggle
toggleTextstringText that appears in the expandable toggle
unmountOnExitbooleanfalseUnmounts tab children (removes them from the DOM) when they are no longer visible
usePageInsetsbooleanFlag indicates that the tabs should use page insets.
variant'default' | 'secondary''default'Tabs background color variant

Tab

*required
NameTypeDefaultDescription
eventKeyrequirednumber | stringuniquely identifies the tab
titlerequiredReact.ReactNodeContent rendered in the tab title. Should be <TabTitleText> and/or <TabTitleIcon> for proper styling.
actionsReact.ReactNodeActions rendered beside the tab content
childrenReact.ReactNodecontent rendered inside the Tab content area.
classNamestringadditional classes added to the Tab
closeButtonAriaLabelstringAria-label for the close button added by passing the onClose property to Tabs.
hrefstringURL associated with the Tab. A Tab with an href will render as an <a> instead of a <button>. A Tab inside a <Tabs component="nav"> should have an href.
inoperableEventsstring[]Events to prevent when the button is in an aria-disabled state
isAriaDisabledbooleanAdds disabled styling and communicates that the button is disabled using the aria-disabled html attribute
isCloseDisabledbooleanFlag indicating the close button should be disabled
isDisabledbooleanAdds disabled styling and disables the button using the disabled html attribute
isHiddenbooleanwhether to render the tab or not
ouiaIdnumber | stringValue to set the data-ouia-component-id for the tab button.
tabContentIdstring | numberchild id for case in which a TabContent section is defined outside of a Tabs component
tabContentRefReact.RefObject<any>child reference for case in which a TabContent section is defined outside of a Tabs component
tooltipReact.ReactElement<any>Optional Tooltip rendered to a Tab. Should be <Tooltip> with appropriate props for proper rendering.

TabContent

*required
NameTypeDefaultDescription
idrequiredstringid passed from parent to identify the content section
activeKeynumber | stringIdentifies the active Tab
aria-labelstringtitle of controlling Tab if used outside Tabs component
childReact.ReactElement<any>Child to show in the content area
childrenanycontent rendered inside the tab content area if used outside Tabs component
classNamestringclass of tab content area if used outside Tabs component
eventKeynumber | stringuniquely identifies the controlling Tab if used outside Tabs component
ouiaIdnumber | stringValue to overwrite the randomly generated data-ouia-component-id.
ouiaSafebooleanSet the value of data-ouia-safe. Only set to true when the component is in a static state, i.e. no animations are occurring. At all other times, this value must be false.

TabTitleText

*required
NameTypeDefaultDescription
childrenrequiredReact.ReactNodeText to be rendered inside the tab button title.
classNamestring''additional classes added to the tab title text

TabTitleIcon

*required
NameTypeDefaultDescription
childrenrequiredReact.ReactNodeIcon to be rendered inside the tab button title.
classNamestring''additional classes added to the tab title icon

TabAction

*required
NameTypeDefaultDescription
aria-labelstringAccessible label for the tab action
childrenReact.ReactNodeContent rendered in the tab action
classNamestringAdditional classes added to the tab action span
isDisabledbooleanFlag indicating if the tab action is disabled
onClick(event: React.MouseEvent<HTMLElement, MouseEvent>) => voidClick callback for tab action button

CSS variables

Expand or collapse columnSelectorVariableValue