Tabs
An accessible tabs component.
The Tab
and TabPanel
elements are associated by their order in the tree.
None of the components are empty wrappers, each is associated with a real DOM
element in the document, giving you maximum control over styling and
composition.
Import#
Usage#
You can render any element within Tabs
, but TabList
should only have Tab
as children, and TabPanels
should have TabPanel
as children.
Tabs expects TabList
and TabPanels
as children. The order doesn't matter,
you can have tabs at the top, at the bottom, or both.
one!
two!
three!
Tab variants and color#
Tabs come in 6 different variants to style the tabs: line
,enclosed
,
enclosed-colored
, soft-rounded
, solid-rounded
, unstyled
one!
two!
You can also change the color for any specific variant by passing the
variantColor
.
The value of variantColor
must exist in the theme object, and must be a key
in theme.colors
that has the 100
- 900
color values.
one!
two!
Tab sizes#
You can change the size of the tab by passing size
prop. We support 3 sizes
sm
, md
, lg
one!
two!
Change the tabs alignment#
You can change the alignment of the TabList
by passing align
prop. We
support 3 sizes start
, center
, end
.
one!
two!
Fitted Tabs#
Stretch the tab list to fit the container by passing isFitted
prop.
one!
two!
Styling the tab states manually#
In event you need to create custom styles for the tabs. Simply set the variant
to unstyled
, and use the _selected
, _hover
, _active
style props.
one!
two!
Tabs onChange#
The onChange
callback returns the active tab's index whenever the user changes
tabs. If you intend to control the tabs programmatically, use this with the
index
prop.
Make a tab initially active#
If you want a tab to be initially active, simply pass the defaultIndex
prop
and set it to the index of that tab.
Make a Tab disabled#
When a Tab
is disabled, it's skipped during keyboard navigation and it's not
clickable.
Manually Activated Tabs#
By default, Tabs
are activated automatically. This means when you use the
arrow keys to change tabs, the tab is activated and focused.
The content of a TabPanel
should ideally be preloaded. However, if switching
to a tab panel causes a network request and possibly a page refresh, there
might be some notable latency and this might affect the experience for
keyboard and screen reader users.
In this scenario, you should use a manually activated tab, it moves focus without activating the tabs. With focus on a specific tab, users can activate a tab by pressing Space or Enter.
one!
two!
Controlled Tabs#
Like form inputs, a tab's state can be controlled. Make sure to include an onChange as well, or else the tabs will not be interactive.
Click the tabs or pull the slider around
Yeah yeah. What's up?
Oh, hello there.
Creating custom tab components#
Because TabList
needs to know the order of the children, we use cloneElement
to pass state internally. If you want to know if a tab is active, you can wrap
it, and then inspect clone props passed in.
Data Tabs#
If you'd like to drive your tabs with an array instead of using the granular components, you can create your own DataTabs component.
Accessibility#
Keyboard#
Key | Action |
---|---|
ArrowLeft | Moves focus to the next tab |
ArrowUp | Moves focus to the previous tab |
Tab | When focus moves into the tab list, places focus on the active tab element |
Space or Enter | Activates the tab if it was not activated automatically on focus |
Home | Moves focus to the first tab |
End | Moves focus to the last tab |
ARIA roles#
Component | Aria | Usage |
---|---|---|
Tab | role="tab" | Indicates that it's a tab |
aria-selected | Set to true a tab is selected and all other Tabs have it set to false . | |
aria-controls | Set to the id of its associated TabPanel | |
TabList | id | The id of the TabPanel that's referencd by its associated Tab |
aria-orientation | Set to vertical or horizontal based on the value of the orientation prop. | |
role="tablist" | Indicates that it's a tablist | |
aria-labelledby | Set to the id of the Tab that labels the TabPanel . |
Props#
Tabs Props#
Tabs composes Box
so you call pass all Box
related props.
Name | Type | Default | Description |
---|---|---|---|
onChange | (index: number) => void | The callback to update the active tab index. | |
index | number | The controlled index of the tabs. | |
defaultIndex | number | The index of the initial active tab. | |
isManual | boolean | If true , keyboard navigation changes focus between tabs but doesn't activate it. User will have to press Enter to active it | |
children | React.ReactNode | The children of the switch. | |
variant | line ,enclosed ,enclosed-colored , soft-rounded , solid-rounded , unstyled | line | The visual style of the tab. |
variantColor | string | The primary color to use for the selected variant. Use a color key in theme.colors | |
size | sm , md , lg | md | The visual size of the tabs |
orientation | horizontal , vertical | horizontal | The orientation of the tabs |
isFitted | boolean | If true , the tabs will stretch to fill the available space |
Tab Props#
Name | Type | Default | Description |
---|---|---|---|
isDisabled | boolean | If true , the tab will be disabled |