Skip to main content
Design system

Tabs

Tabs are used to navigate between sections of content in the same area without reloading the page.

Bundle size: 5.6 kB
Install:
npm install @washingtonpost/wpds-ui-kit
|Copy
Usage:
import { Tabs } from "@washingtonpost/wpds-ui-kit"
|Copy
Storybook:  View on Storybook
Source:  View on Github

Anatomy

Note: Image is not to scale

  1. Tab
  2. Selection indicator
  3. Icon (optional)
  4. 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.


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

Tabs

PropDescriptionTypeDefaultRequired

TabsRoot

PropDescriptionTypeDefaultRequired
defaultValueThe value of the tab to select by default, if uncontrolled
string
----False
dirThe direction of navigation between toolbar items.
Direction
----False
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
asChild
boolean
----False
valueThe value for the selected tab, if controlled
string
----False
onValueChangeA function called when a new tab is selected
(value: string) => void
----False
orientationThe orientation the tabs are layed out. Mainly so arrow navigation is done accordingly (left & right vs. up & down) @defaultValue horizontal
"horizontal" | "vertical"
----False
activationModeWhether a tab is activated automatically or manually. @defaultValue automatic
"manual" | "automatic"
----False
cssWPDS 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?: AlignContent | Globals | ScaleValue | Index; alignItems?: AlignItems | Globals | ScaleValue | Index; ... 426 more ...; vectorEffect?: VectorEffect | ... 2 more ... | Index; } & ... 7 more ... & { ...; }
----False

TabsList

PropDescriptionTypeDefaultRequired
asChild
boolean
----False
loop
boolean
----False
cssWPDS 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: ${string})`; md: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; lg: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xxl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; notS...
----False
alignthe alignment of the list content along the tab bar. Default is left aligned
("left" | "center") & ("left" | "center" | ({ "@sm"?: "left" | "center"; "@md"?: "left" | "center"; "@lg"?: "left" | "center"; "@xl"?: "left" | "center"; "@xxl"?: "left" | "center"; "@notSm"?: "left" | "center"; ... 18 more ...; "@initial"?: "left" | "center"; } & { ...; }))
left False
densitythe overall size of the component. Default is default (theme.fontSizes[100])
"default" | "loose" | "compact"
default False

TabsTrigger

PropDescriptionTypeDefaultRequired
valueA unique value that associates the trigger with a content.
string
----
True
disabledThe value whether the trigger should be disabled
boolean
----False
cssWPDS 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?: AlignContent | Globals | ScaleValue | Index; alignItems?: AlignItems | Globals | ScaleValue | Index; ... 426 more ...; vectorEffect?: VectorEffect | ... 2 more ... | Index; } & ... 7 more ... & { ...; }
----False
asChild
boolean
----False
density
"default" | "loose" | "compact" | ({ "@sm"?: "default" | "loose" | "compact"; "@md"?: "default" | "loose" | "compact"; "@lg"?: "default" | "loose" | "compact"; "@xl"?: "default" | "loose" | "compact"; ... 20 more ...; "@initial"?: "default" | ... 1 more ... | "compact"; } & { ...; })
----False
active
boolean | "true" | ({ "@sm"?: boolean | "true"; "@md"?: boolean | "true"; "@lg"?: boolean | "true"; "@xl"?: boolean | "true"; "@xxl"?: boolean | "true"; "@notSm"?: boolean | "true"; "@notMd"?: boolean | "true"; ... 17 more ...; "@initial"?: boolean | "true"; } & { ...; })
----False

TabsContent

PropDescriptionTypeDefaultRequired
value
string
----
True
cssWPDS 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
forceMountUsed to force mounting when more control is needed. Useful when controlling animation with React animation libraries.
true
----False
asChild
boolean
----False
Edit this page on GitHub.