sp-tabs

Examples API

Attributes and Properties #

Property Attribute Type Default Description
auto auto boolean false Whether to activate a tab on keyboard focus or not.

By default a tab is activated via a "click" interaction. This is specifically intended for when tab content cannot be displayed instantly, e.g. not all of the DOM content is available, etc. To learn more about "Deciding When to Make Selection Automatically Follow Focus", visit: https://w3c.github.io/aria-practices/#kbd_selection_follows_focus

autofocus autofocus boolean false When this control is rendered, focus it automatically
undefined compact Boolean The collection of tabs take up less space
dir dir 'ltr' | 'rtl' 'ltr'
direction direction 'vertical' | 'vertical-right' | 'horizontal' 'horizontal'
disabled disabled boolean false Disable this control. It will not receive focus or events
label label string ''
undefined quiet Boolean The tabs border is a lot smaller
selected selected string
size size ElementSize
tabIndex tabIndex number The tab index to apply to this control. See general documentation about the tabindex HTML property

Slots #

Name Description
default slot Tab elements to manage as a group
tab-panel Tab Panel elements related to the listed Tab elements

Events #

Name Type Description
change Event The selected Tab child has changed.

CSS Custom Properties #

Name Default
--spectrum-tabs-l-compact-item-height var(--spectrum-global-dimension-size-500)
--spectrum-tabs-l-compact-quiet-height var(--spectrum-global-dimension-size-500)
--spectrum-tabs-l-compact-vertical-item-gap var(--spectrum-global-dimension-size-65)
--spectrum-tabs-l-compact-vertical-item-height var(--spectrum-global-dimension-size-500)
--spectrum-tabs-l-divider-border-radius var(--spectrum-global-dimension-static-size-10)
--spectrum-tabs-l-divider-size var(--spectrum-alias-border-size-thick)
--spectrum-tabs-l-focus-ring-border-radius undefined
--spectrum-tabs-l-focus-ring-height var(--spectrum-global-dimension-size-500)
--spectrum-tabs-l-focus-ring-padding-x var(--spectrum-global-dimension-size-185)
--spectrum-tabs-l-focus-ring-size var(--spectrum-alias-border-size-thick)
--spectrum-tabs-l-icon-gap var(--spectrum-global-dimension-size-115)
--spectrum-tabs-l-item-gap var(--spectrum-global-dimension-size-350)
--spectrum-tabs-l-item-height var(--spectrum-global-dimension-size-500)
--spectrum-tabs-l-selection-indicator-animation-duration var(--spectrum-global-animation-duration-100)
--spectrum-tabs-l-text-font-weight var(--spectrum-alias-body-text-font-weight)
--spectrum-tabs-l-text-size var(--spectrum-global-dimension-font-size-200)
--spectrum-tabs-l-vertical-divider-size var(--spectrum-alias-border-size-thick)
--spectrum-tabs-l-vertical-item-gap var(--spectrum-global-dimension-size-65)
--spectrum-tabs-l-vertical-item-height var(--spectrum-global-dimension-size-650)
--spectrum-tabs-l-vertical-item-margin-left var(--spectrum-global-dimension-size-160)
--spectrum-tabs-m-compact-item-height var(--spectrum-global-dimension-size-400)
--spectrum-tabs-m-compact-quiet-height var(--spectrum-global-dimension-size-400)
--spectrum-tabs-m-compact-vertical-item-gap var(--spectrum-global-dimension-size-50)
--spectrum-tabs-m-compact-vertical-item-height var(--spectrum-global-dimension-size-400)
--spectrum-tabs-m-divider-border-radius var(--spectrum-global-dimension-static-size-10)
--spectrum-tabs-m-divider-color var(--spectrum-alias-border-color-light)
--spectrum-tabs-m-divider-size var(--spectrum-alias-border-size-thick)
--spectrum-tabs-m-focus-ring-border-radius undefined
--spectrum-tabs-m-focus-ring-color var(--spectrum-alias-border-color-key-focus)
--spectrum-tabs-m-focus-ring-height var(--spectrum-global-dimension-size-400)
--spectrum-tabs-m-focus-ring-padding-x var(--spectrum-global-dimension-size-150)
--spectrum-tabs-m-focus-ring-size var(--spectrum-alias-border-size-thick)
--spectrum-tabs-m-icon-color var(--spectrum-alias-icon-color)
--spectrum-tabs-m-icon-color-disabled var(--spectrum-alias-icon-color-disabled)
--spectrum-tabs-m-icon-color-hover var(--spectrum-alias-icon-color-hover)
--spectrum-tabs-m-icon-color-key-focus var(--spectrum-alias-icon-color-key-focus)
--spectrum-tabs-m-icon-color-selected var(--spectrum-global-color-gray-900)
--spectrum-tabs-m-icon-gap var(--spectrum-global-dimension-size-100)
--spectrum-tabs-m-item-gap var(--spectrum-global-dimension-size-300)
--spectrum-tabs-m-item-height var(--spectrum-global-dimension-size-400)
--spectrum-tabs-m-quiet-divider-color var(--spectrum-alias-border-color-transparent)
--spectrum-tabs-m-quiet-selection-indicator-color var(--spectrum-global-color-gray-900)
--spectrum-tabs-m-selection-indicator-animation-duration var(--spectrum-global-animation-duration-100)
--spectrum-tabs-m-selection-indicator-color var(--spectrum-global-color-gray-900)
--spectrum-tabs-m-text-color var(--spectrum-alias-label-text-color)
--spectrum-tabs-m-text-color-disabled var(--spectrum-alias-text-color-disabled)
--spectrum-tabs-m-text-color-hover var(--spectrum-alias-text-color-hover)
--spectrum-tabs-m-text-color-key-focus var(--spectrum-alias-text-color-hover)
--spectrum-tabs-m-text-color-selected var(--spectrum-global-color-gray-900)
--spectrum-tabs-m-text-font-weight var(--spectrum-alias-body-text-font-weight)
--spectrum-tabs-m-text-size var(--spectrum-global-dimension-font-size-100)
--spectrum-tabs-m-vertical-divider-color var(--spectrum-alias-border-color-light)
--spectrum-tabs-m-vertical-divider-size var(--spectrum-alias-border-size-thick)
--spectrum-tabs-m-vertical-item-gap var(--spectrum-global-dimension-size-50)
--spectrum-tabs-m-vertical-item-height var(--spectrum-global-dimension-size-550)
--spectrum-tabs-m-vertical-item-margin-left var(--spectrum-global-dimension-size-150)
--spectrum-tabs-m-vertical-quiet-divider-color var(--spectrum-alias-border-color-transparent)
--spectrum-tabs-s-compact-item-height var(--spectrum-global-dimension-size-300)
--spectrum-tabs-s-compact-quiet-height var(--spectrum-global-dimension-size-300)
--spectrum-tabs-s-compact-vertical-item-gap var(--spectrum-global-dimension-size-50)
--spectrum-tabs-s-compact-vertical-item-height var(--spectrum-global-dimension-size-300)
--spectrum-tabs-s-divider-border-radius var(--spectrum-global-dimension-static-size-10)
--spectrum-tabs-s-divider-size var(--spectrum-alias-border-size-thick)
--spectrum-tabs-s-focus-ring-border-radius undefined
--spectrum-tabs-s-focus-ring-height var(--spectrum-global-dimension-size-300)
--spectrum-tabs-s-focus-ring-padding-x var(--spectrum-global-dimension-size-115)
--spectrum-tabs-s-focus-ring-size var(--spectrum-alias-border-size-thick)
--spectrum-tabs-s-icon-gap var(--spectrum-global-dimension-size-85)
--spectrum-tabs-s-item-gap var(--spectrum-global-dimension-size-250)
--spectrum-tabs-s-item-height var(--spectrum-global-dimension-size-300)
--spectrum-tabs-s-selection-indicator-animation-duration var(--spectrum-global-animation-duration-100)
--spectrum-tabs-s-text-font-weight var(--spectrum-alias-body-text-font-weight)
--spectrum-tabs-s-text-size var(--spectrum-global-dimension-font-size-75)
--spectrum-tabs-s-vertical-divider-size var(--spectrum-alias-border-size-thick)
--spectrum-tabs-s-vertical-item-gap var(--spectrum-global-dimension-size-50)
--spectrum-tabs-s-vertical-item-height var(--spectrum-global-dimension-size-450)
--spectrum-tabs-s-vertical-item-margin-left var(--spectrum-global-dimension-size-150)
--spectrum-tabs-xl-compact-item-height var(--spectrum-global-dimension-size-600)
--spectrum-tabs-xl-compact-quiet-height var(--spectrum-global-dimension-size-600)
--spectrum-tabs-xl-compact-vertical-item-gap var(--spectrum-global-dimension-size-65)
--spectrum-tabs-xl-compact-vertical-item-height var(--spectrum-global-dimension-size-600)
--spectrum-tabs-xl-divider-border-radius var(--spectrum-global-dimension-static-size-10)
--spectrum-tabs-xl-divider-size var(--spectrum-alias-border-size-thick)
--spectrum-tabs-xl-focus-ring-border-radius undefined
--spectrum-tabs-xl-focus-ring-height var(--spectrum-global-dimension-size-600)
--spectrum-tabs-xl-focus-ring-padding-x var(--spectrum-global-dimension-size-225)
--spectrum-tabs-xl-focus-ring-size var(--spectrum-alias-border-size-thick)
--spectrum-tabs-xl-icon-gap var(--spectrum-global-dimension-size-125)
--spectrum-tabs-xl-item-gap var(--spectrum-global-dimension-size-400)
--spectrum-tabs-xl-item-height var(--spectrum-global-dimension-size-600)
--spectrum-tabs-xl-selection-indicator-animation-duration var(--spectrum-global-animation-duration-100)
--spectrum-tabs-xl-text-font-weight var(--spectrum-alias-body-text-font-weight)
--spectrum-tabs-xl-text-size var(--spectrum-global-dimension-font-size-300)
--spectrum-tabs-xl-vertical-divider-size var(--spectrum-alias-border-size-thick)
--spectrum-tabs-xl-vertical-item-gap var(--spectrum-global-dimension-size-65)
--spectrum-tabs-xl-vertical-item-height var(--spectrum-global-dimension-size-750)
--spectrum-tabs-xl-vertical-item-margin-left var(--spectrum-global-dimension-size-160)

Description #

The <sp-tabs> displays a list of <sp-tab> element children as role="tablist". An <sp-tab> element is associated with a sibling <sp-tab-panel> element via their value attribute. When an <sp-tab> element is selected, the associated <sp-tab-panel> will also be selected, showing that panel and hiding the others.

Usage #

See it on NPM! How big is this package in your project? Try it on webcomponents.dev

yarn add @spectrum-web-components/tabs

Import the side effectful registration of <sp-tabs>, <sp-tab> or <sp-tab-panel> via:

import '@spectrum-web-components/tabs/sp-tabs.js';
import '@spectrum-web-components/tabs/sp-tab.js';
import '@spectrum-web-components/tabs/sp-tab-panel.js';

When looking to leverage the Tabs, Tab, or TabPanel base class as a type and/or for extension purposes, do so via:

import {
    Tabs,
    Tab,
    TabPanel
} from '@spectrum-web-components/tabs';

Sizes #

Small
<sp-tabs selected="1" size="s">
<sp-tab label="Tab 1" value="1"></sp-tab>
<sp-tab label="Tab 2" value="2"></sp-tab>
<sp-tab label="Tab 3" value="3"></sp-tab>
<sp-tab label="Tab 4" value="4"></sp-tab>
<sp-tab-panel value="1">Content for Tab 1</sp-tab-panel>
<sp-tab-panel value="2">Content for Tab 2</sp-tab-panel>
<sp-tab-panel value="3">Content for Tab 3</sp-tab-panel>
<sp-tab-panel value="4">Content for Tab 4</sp-tab-panel>
</sp-tabs>
Medium
<sp-tabs selected="1" size="m">
<sp-tab label="Tab 1" value="1"></sp-tab>
<sp-tab label="Tab 2" value="2"></sp-tab>
<sp-tab label="Tab 3" value="3"></sp-tab>
<sp-tab label="Tab 4" value="4"></sp-tab>
<sp-tab-panel value="1">Content for Tab 1</sp-tab-panel>
<sp-tab-panel value="2">Content for Tab 2</sp-tab-panel>
<sp-tab-panel value="3">Content for Tab 3</sp-tab-panel>
<sp-tab-panel value="4">Content for Tab 4</sp-tab-panel>
</sp-tabs>
Large
<sp-tabs selected="1" size="l">
<sp-tab label="Tab 1" value="1"></sp-tab>
<sp-tab label="Tab 2" value="2"></sp-tab>
<sp-tab label="Tab 3" value="3"></sp-tab>
<sp-tab label="Tab 4" value="4"></sp-tab>
<sp-tab-panel value="1">Content for Tab 1</sp-tab-panel>
<sp-tab-panel value="2">Content for Tab 2</sp-tab-panel>
<sp-tab-panel value="3">Content for Tab 3</sp-tab-panel>
<sp-tab-panel value="4">Content for Tab 4</sp-tab-panel>
</sp-tabs>
Extra Large
<sp-tabs selected="1" size="xl">
<sp-tab label="Tab 1" value="1"></sp-tab>
<sp-tab label="Tab 2" value="2"></sp-tab>
<sp-tab label="Tab 3" value="3"></sp-tab>
<sp-tab label="Tab 4" value="4"></sp-tab>
<sp-tab-panel value="1">Content for Tab 1</sp-tab-panel>
<sp-tab-panel value="2">Content for Tab 2</sp-tab-panel>
<sp-tab-panel value="3">Content for Tab 3</sp-tab-panel>
<sp-tab-panel value="4">Content for Tab 4</sp-tab-panel>
</sp-tabs>

Disabled #

When an <sp-tabs> element is given the disabled attribute its <sp-tab> children will be disabled as well, preventing a visitor from changing the selected tab. By default, <sp-tab-panel> children will not be addressed and the available content of the currently selected tab will be fully visible.

<sp-tabs selected="2" disabled>
<sp-tab label="Tab 1" value="1"></sp-tab>
<sp-tab label="Tab 2" value="2"></sp-tab>
<sp-tab label="Tab 3" value="3"></sp-tab>
<sp-tab label="Tab 4" value="4"></sp-tab>
<sp-tab-panel value="1">Content for Tab 1 is not selectable</sp-tab-panel>
<sp-tab-panel value="2">Content for Tab 2 is selected</sp-tab-panel>
<sp-tab-panel value="3">Content for Tab 3 is not selectable</sp-tab-panel>
<sp-tab-panel value="4">Content for Tab 4 is not selectable</sp-tab-panel>
</sp-tabs>

Vertical #

<sp-tabs selected="1" direction="vertical">
<sp-tab label="Tab 1" value="1"></sp-tab>
<sp-tab label="Tab 2" value="2"></sp-tab>
<sp-tab label="Tab 3" value="3"></sp-tab>
<sp-tab label="Tab 4" value="4"></sp-tab>
<sp-tab-panel value="1">Content for Tab 1</sp-tab-panel>
<sp-tab-panel value="2">Content for Tab 2</sp-tab-panel>
<sp-tab-panel value="3">Content for Tab 3</sp-tab-panel>
<sp-tab-panel value="4">Content for Tab 4</sp-tab-panel>
</sp-tabs>

Variants #

Quiet #

<sp-tabs selected="1" quiet>
<sp-tab label="Tab 1" value="1"></sp-tab>
<sp-tab label="Tab 2" value="2"></sp-tab>
<sp-tab label="Tab 3" value="3"></sp-tab>
<sp-tab label="Tab 4" value="4"></sp-tab>
<sp-tab-panel value="1">Content for Tab 1</sp-tab-panel>
<sp-tab-panel value="2">Content for Tab 2</sp-tab-panel>
<sp-tab-panel value="3">Content for Tab 3</sp-tab-panel>
<sp-tab-panel value="4">Content for Tab 4</sp-tab-panel>
</sp-tabs>

Compact #

<sp-tabs selected="1" compact>
<sp-tab label="Tab 1" value="1"></sp-tab>
<sp-tab label="Tab 2" value="2"></sp-tab>
<sp-tab label="Tab 3" value="3"></sp-tab>
<sp-tab label="Tab 4" value="4"></sp-tab>
<sp-tab-panel value="1">Content for Tab 1</sp-tab-panel>
<sp-tab-panel value="2">Content for Tab 2</sp-tab-panel>
<sp-tab-panel value="3">Content for Tab 3</sp-tab-panel>
<sp-tab-panel value="4">Content for Tab 4</sp-tab-panel>
</sp-tabs>

With icons #

<div>
<sp-icons-medium></sp-icons-medium>
<sp-tabs selected="1" direction="horizontal">
<sp-tab label="Tab 1" value="1">
<sp-icon-checkmark slot="icon"></sp-icon-checkmark>
</sp-tab>
<sp-tab label="Tab 2" value="2">
<sp-icon-close slot="icon"></sp-icon-close>
</sp-tab>
<sp-tab label="Tab 3" value="3">
<sp-icon-chevron-down slot="icon"></sp-icon-chevron-down>
</sp-tab>
<sp-tab label="Tab 4" value="4">
<sp-icon-help slot="icon"></sp-icon-help>
</sp-tab>
<sp-tab-panel value="1">Content for Tab 1</sp-tab-panel>
<sp-tab-panel value="2">Content for Tab 2</sp-tab-panel>
<sp-tab-panel value="3">Content for Tab 3</sp-tab-panel>
<sp-tab-panel value="4">Content for Tab 4</sp-tab-panel>
</sp-tabs>
</div>

Accessibility #

When an <sp-tabs> has a selected value, the <sp-tab> child of that value will be given [tabindex="0"] and will receive initial focus when tabbing into the <sp-tabs> element. When no selected value is present, the first <sp-tab> child will be treated in this way. When focus is currently within the <sp-tabs> element, the left and right arrows will move that focus back and forth through the available <sp-tab> children.