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.14 kB
Install:
npm install @washingtonpost/wpds-ui-kit
|Copy
Usage:
import { Tabs } from "@washingtonpost/wpds-ui-kit"
|Copy
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

TabsRoot

PropDescriptionTypeDefaultRequired
defaultValueThe value of the tab to select by default, if uncontrolled
string
False
dirThe direction of navigation between toolbar items.
enum
Direction
----False
childrenAny React node may be used as a child to allow for formatting
enum
ReactNode
----False
asChild
enum
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
enum
horizontal | vertical
----False
activationModeWhether a tab is activated automatically or manually. @defaultValue automatic
enum
automatic | manual
----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?: Globals | ScaleValue | Index | AlignContent; alignItems?: Globals | ScaleValue | Index | AlignItems; ... 425 more ...; vectorEffect?: Globals | ... 2 more ... | VectorEffect; } & ... 7 more ... & { ...; }
----False

TabsList

PropDescriptionTypeDefaultRequired
asChild
enum
boolean
----False
loop
enum
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: 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
alignthe alignment of the list content along the tab bar. Default is left aligned
enum
(left | center) & (left | center
left False
densitythe overall size of the component. Default is default (theme.fontSizes[100])
enum
default | loose | compact
----False

TabsTrigger

PropDescriptionTypeDefaultRequired
valueThe value for the selected tab, if controlled
string
----
True
disabledThe value whether the trigger should be disabled
enum
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?: Globals | ScaleValue | Index | AlignContent; alignItems?: Globals | ScaleValue | Index | AlignItems; ... 425 more ...; vectorEffect?: Globals | ... 2 more ... | VectorEffect; } & ... 7 more ... & { ...; }
----False
activeWhether the current tabs trigger is currently active
enum
boolean & (boolean | true
----False
previousRectKeeps track of the previously active tab location
DOMRect
----False
setPreviousRectsetter for the previously active tab location
Dispatch<SetStateAction<DOMRect>>
----False
asChild
enum
boolean
----False
density
enum
default | loose | compact
----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
enum
boolean
----False