Anatomy
Note: Image is not to scale
- Tab
- Selection indicator
- Icon (optional)
- Tab bar
Options
Selection
This option indicates whether a tab is selected (and thereby showing content) or not.
Alignment
This option determines whether the tabs are left or center aligned along the tab bar.
Density
This option determines the overall size of the component: compact, default, or loose.
Behavior
Hover
Hovering over an unselected tab causes a lighter selection bar to appear below.
Disabled
A disabled tab changes to color subtle.
Tab overflow
When there are more tabs than can be displayed, the behavior will match our secondary navigation. The tabs will be cut off and hidden on the far right and accessible via scrolling.
Guidance
Tab number
Use at least 2 tabs or more.
Text overflow
Avoid using long titles for tab copy. Thirty characters or less is our recommendation. If text does overflow, it is truncated with an ellipsis and the full text is shown in a tooltip on hover.
Icon placement
Don't put icons on the right.
Linking
Tabs should not link to another page.
Icons
When using icons, it is best to use them as a prefix to the label, rather than following the label. This ensures that the icon is properly associated with the label and is more easily recognizable by users. For example, use a 'search' icon before the label 'Search" rathern than after it.
Accessibility
Keyboard interactions
Using the left and right arrow keys will move focus between tabs. You can press enter to make that focused tab active.
API Reference
TabsRoot
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| defaultValue | The value of the tab to select by default, if uncontrolled | string | False | |
| dir | The direction of navigation between toolbar items. | enum Direction | ---- | False |
| children | Any React node may be used as a child to allow for formatting | enum ReactNode | ---- | False |
| asChild | enum boolean | ---- | False | |
| value | The value for the selected tab, if controlled | string | ---- | False |
| onValueChange | A function called when a new tab is selected | (value: string) => void | ---- | False |
| orientation | The orientation the tabs are layed out. Mainly so arrow navigation is done accordingly (left & right vs. up & down) @defaultValue horizontal | enum horizontal | vertical | ---- | False |
| activationMode | Whether a tab is activated automatically or manually. @defaultValue automatic | enum automatic | manual | ---- | False |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | {} & { alignContent?: Globals | ScaleValue | Index | AlignContent; alignItems?: Globals | ScaleValue | Index | AlignItems; ... 425 more ...; vectorEffect?: Globals | ... 2 more ... | VectorEffect; } & ... 7 more ... & { ...; } | ---- | False |
TabsList
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| asChild | enum boolean | ---- | False | |
| loop | enum boolean | ---- | False | |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS<{ sm: `(max-width: calc(${string} - 1px))`; md: `(min-width: ${string}) and (max-width: calc(${string} - 1px))`; lg: `(min-width: ${string}) and (max-width: calc(${string} - 1px))`; xl: `(min-width: ${string}) and (max-width: calc(${string} - 1px))`; xxl: `(min-width: ${string}) and (max-width: ${string})`; notS... | ---- | False |
| align | the alignment of the list content along the tab bar. Default is left aligned | enum (left | center) & (left | center | left | False |
| density | the overall size of the component. Default is default (theme.fontSizes[100]) | enum default | loose | compact | ---- | False |
TabsTrigger
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| value | The value for the selected tab, if controlled | string | ---- | True |
| disabled | The value whether the trigger should be disabled | enum boolean | ---- | False |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | {} & { alignContent?: Globals | ScaleValue | Index | AlignContent; alignItems?: Globals | ScaleValue | Index | AlignItems; ... 425 more ...; vectorEffect?: Globals | ... 2 more ... | VectorEffect; } & ... 7 more ... & { ...; } | ---- | False |
| active | Whether the current tabs trigger is currently active | enum boolean & (boolean | true | ---- | False |
| previousRect | Keeps track of the previously active tab location | DOMRect | ---- | False |
| setPreviousRect | setter for the previously active tab location | Dispatch<SetStateAction<DOMRect>> | ---- | False |
| asChild | enum boolean | ---- | False | |
| density | enum default | loose | compact | ---- | False |
TabsContent
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| value | string | ---- | True | |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS | ---- | False |
| forceMount | Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries. | true | ---- | False |
| asChild | enum boolean | ---- | False |