Tabs - Elements

Tabs are used to group content, allowing users to navigate views without leaving the page.

AndroidreleasedElementsreleasediOSreleasedReactreleasedVuereleased

AndroidElementsiOSReactVue

Example theme:

DBA lightFinn lightTori lightBlocket lightNeutral lightVend lightDBA darkFinn darkTori darkBlocket darkNeutral darkVend dark

Accessibility

The tabs component follows the WAI-ARIA Tabs pattern:

• The tab list gets role="tablist"
• Each tab button gets role="tab" with aria-selected reflecting its active state
• Each tab button gets aria-controls pointing to its associated panel
• Each panel gets role="tabpanel" with aria-labelledby pointing to its associated tab
• Keyboard navigation is supported:
  • ArrowLeft/ArrowRight: Navigate between tabs
  • Home: Move to first tab
  • End: Move to last tab

Usage

The tabs component consists of three custom elements that work together:

• <w-tabs> - The container that manages tab state and keyboard navigation
• <w-tab> - Individual tab buttons
• <w-tab-panel> - Content panels associated with each tab

Each <w-tab> has a for attribute that matches the id of its corresponding <w-tab-panel>.

Examples

<w-tabs>
  <w-tab for="roald-amundsen">Tab 1</w-tab>
  <w-tab for="fridtjof-nansen">Tab 2</w-tab>
  <w-tab for="tor-heyerdahl">Tab 3</w-tab>
  <w-tab-panel id="roald-amundsen">Tab one selected!</w-tab-panel>
  <w-tab-panel id="fridtjof-nansen">Tab two selected!</w-tab-panel>
  <w-tab-panel id="tor-heyerdahl">Tab three selected!</w-tab-panel>
</w-tabs>

<script type="module">
  const tabs = document.querySelector('w-tabs');

  tabs.addEventListener('change', (event) => {
    // event.detail = { panelId: string }
    console.log('Active panel:', event.detail.panelId);
  });
</script>

Tabs with icons

Icons can be added to tabs using the icon slot. By default, icons appear beside the label.

<w-tabs active="fridtjof-nansen">
  <w-tab for="roald-amundsen">
    <w-icon name="Info" slot="icon"></w-icon>
    Tab 1
  </w-tab>
  <w-tab for="fridtjof-nansen">
    <w-icon name="Success" slot="icon"></w-icon>
    Tab 2
  </w-tab>
  <w-tab-panel id="roald-amundsen">Content one</w-tab-panel>
  <w-tab-panel id="fridtjof-nansen">Content two</w-tab-panel>
</w-tabs>

Use the over attribute to position icons above the label:

<w-tabs>
  <w-tab for="roald-amundsen" over>
    <w-icon name="Info" slot="icon"></w-icon>
    Tab 1
  </w-tab>
  <w-tab for="fridtjof-nansen" over>
    <w-icon name="Success" slot="icon"></w-icon>
    Tab 2
  </w-tab>
  <w-tab-panel id="roald-amundsen">Content one</w-tab-panel>
  <w-tab-panel id="fridtjof-nansen">Content two</w-tab-panel>
</w-tabs>

Styling API

Tabs support styling through component tokens (CSS custom properties with a --w-c prefix) and parts.

Parts

Use ::part(part-name) from outside the component.

<w-tabs> parts

• base - the root element inside the component.
• tablist - the container for all the tabs (not the tab panels).
• selection - the indicator for the active tab.

<w-tab> parts

• base - the root element inside the component.
• icon-inline - the icon when shown inline with the tab name.
• icon-block - the icon when shown above the tab name.

<w-tab-panel> parts

• base - the root element inside the component.

Component tokens

<w-tabs> tokens

Set these on <w-tabs> to override visuals.

w-tabs {
	--w-c-tabs-selection-color: limegreen;
}

• --w-c-tabs-border-width
• --w-c-tabs-border-color
• --w-c-tabs-selection-width
• --w-c-tabs-selection-color

<w-tab> tokens

Set these on <w-tab> to override visuals.

w-tab {
	--w-c-tab-active-color: magenta;
}

• --w-c-tab-inactive-color
• --w-c-tab-hover-color
• --w-c-tab-hover-color-border
• --w-c-tab-active-color
• --w-c-tab-active-color-border

<w-tab-panel> tokens

<w-tab-panel> has no tokens.

<w-tabs> API

Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

Properties

Name	Type	Default	Summary
active	string | undefined	"" (Shows the first tab)	The id of the panel that should be active.

Property Details

active

The id of the panel that should be active.

• Type: string | undefined
• Default: "" (Shows the first tab)

Events

change

Includes details.panelId with the now active tab panel's ID

• Type: WarpTabsChangeEvent

Types

ResizeObserver | undefined

{ disconnect: { }, observe: { }, unobserve: { } } | undefined

WarpTabsChangeEvent

{ detail: { panelId: string }, initCustomEvent: { }, bubbles: boolean, cancelBubble: boolean, cancelable: boolean, composed: boolean, currentTarget: null | { addEventListener: { }, dispatchEvent: { }, removeEventListener: { } }, defaultPrevented: boolean, eventPhase: number, isTrusted: boolean, returnValue: boolean, srcElement: null | { addEventListener: { }, dispatchEvent: { }, removeEventListener: { } }, target: null | { addEventListener: { }, dispatchEvent: { }, removeEventListener: { } }, timeStamp: number, type: string, composedPath: { }, initEvent: { }, preventDefault: { }, stopImmediatePropagation: { }, stopPropagation: { }, NONE: 0, CAPTURING_PHASE: 1, AT_TARGET: 2, BUBBLING_PHASE: 3 }

<w-tab> API

Properties

Name	Type	Default	Summary
_internals (JS only)	unknown	-	-
for	string | undefined	-	The id of the <w-tab-panel> this tab controls.
over	boolean	false	Whether to show the icon slot over the tab title instead of inline.
tabindex	number	0	The host element (<w-tab>), the one with role=tab, must be the focusable element for assistive technology.

Property Details

_internals (JS only)

• Type: unknown
• Default: -

for

The id of the <w-tab-panel> this tab controls.

• Type: string | undefined
• Default: -

over

Whether to show the icon slot over the tab title instead of inline.

• Type: boolean
• Default: false

tabindex

The host element (<w-tab>), the one with role=tab, must be the focusable element for assistive technology.

• Type: number
• Default: 0

<w-tab-panel> API

Properties

Name	Type	Default	Summary
id	string	-	Required so <w-tab> has something to target.

Property Details

id

Required so <w-tab> has something to target.

• Type: string
• Default: -

Types

boolean | undefined

false | true | undefined

Questions?

Feel free to ask any questions on usage in the Warp DS Slack channel: #warp-design-system