BRAID
Braid Design System
GuidesFoundationsComponentsPatternsStyles

Tabs

A horizontally arranged group of buttons that control the visibility of the associated content panels.
Panel 1
 
Open in Playroom

Accessibility

Follows the WAI ARIA Tabs Pattern.

Appearance

Alignment

Tabs are left aligned by default, but this can be customised via the align prop on Tabs.
Panel 1
 
Open in Playroom

Dividers

Increasing divider width

In cases where you only have a couple of tabs, you may find that the tab strip lacks visual affordance. To address this, you can set the divider prop to “full” on the Tabs component.
Panel 1
 
Open in Playroom

Hiding the divider

If you've placed the tab strip and tab content on different backgrounds, the divider line is likely to be redundant visual noise. To hide it, you can set the divider prop to “none” on the Tabs component.
Panel 1
 
Open in Playroom

Size

Customise the size of the Tabs via the size prop, which accepts either standard or small.
Standard tabs
Small tabs
 
Open in Playroom

Icons

For decoration or help distinguishing between tabs, an icon can be provided. This will be placed to the left of the label.
Panel 1
 
Open in Playroom

Badges

Add a Badge alongside the Tab by using the badge prop.
Panel 1
 
Open in Playroom

Layout

Placement

The Tabs and TabPanels components can be positioned wherever you like, e.g. the tab panels can be nested within a Card while the tabs sit above the card.

Reserve hit area

By default, a Tab will only occupy the vertical space from the top of the label to the active underline. This means the hit area will bleed out into the space above.The bleed can be disabled by setting the reserveHitArea prop to true.
 
Open in Playroom

Gutters

Tabs are horizontally scrollable when they’re too wide to fit on screen. If you’d like to align the tabs with content below them (e.g. when the tab panels are inside a card but the tabs are outside), you can provide a gutter prop to Tabs that accepts a value from Braid’s space scale.
Panel 1
 
Open in Playroom

Interaction

State management

Tabs manage their own state by default. If you’d like to manage the state yourself, you must pass an item prop to each Tab and TabPanel element, as well as selectedItem and onChange props to TabsProvider.
Panel 2
 
Open in Playroom

Best practices

Development considerations

All tab components must be nested within a TabsProvider which provides the state.Somewhere within TabsProvider you must:
  • Provide a Tabs component containing multiple Tab components.
  • Provide a TabsPanels component containing multiple TabPanel components.

When to use

Use Tabs when:
  • you have a small, fixed set of related sections
  • users need to view one section at a time
  • the content shares the same context.
Don’t use Tabs when:
  • users need to compare sections or view them at the same time (use a Card List or Divided List instead)
  • the content is a linear, as in a step-by-step flow (use a Stepper instead)
  • the information is critical and shouldn’t risk being missed inside a tab (surface upfront instead)

Data attributes

Braid components are very explicit about the properties they accept, which makes providing arbitrary data attributes not possible. Instead, a data prop can be provided as a single collection of data attributes.
<TabsProvider>
  <Tabs
    data={{ testid: 'tabs-1' }}
    // => data-testid="tabs-1"
  >
    <Tab data={{ testid: 'tab-1' }}>
      ...
    </Tab>
  </Tabs>
  <TabPanels>
    <TabPanel data={{ testid: 'tab-panel-1' }}>
      ...
    </TabPanel>
  </TabPanels>
</TabsProvider>

Alternatives

  • Accordion — For a vertical, expandable list of content sections.
On this page