Skip to contentSkip to navigationSkip to topbar
Paste
Paste assistant Assistant
FigmaStar

Tabs

Version 8.2.1GithubStorybook

Tabs are labeled controls that allow users to switch between multiple views within a page.

Installation

Installation page anchor
yarn add @twilio-paste/tabs - or - yarn add @twilio-paste/core

Usage

Usage page anchor
import {Tabs, TabList, Tab, TabPanels, TabPanel} from '@twilio-paste/core/tabs';

const HorizontalTabsExample: React.FC = () => {
  const selectedId = useUID();
  return (
    <Tabs selectedId={selectedId} baseId="horizontal-tabs-example">
      <TabList aria-label="My tabs">
        <Tab>Tab 1</Tab>
        <Tab disabled>Tab 2</Tab>
        <Tab id={selectedId}>Tab 3</Tab>
      </TabList>
      <TabPanels paddingTop="space20">
        <TabPanel>Tab 1</TabPanel>
        <TabPanel>Tab 2</TabPanel>
        <TabPanel>Tab 3</TabPanel>
      </TabPanels>
    </Tabs>
  );
};

Props

Props page anchor

Tabs

Tabs page anchor

baseId

ID that will serve as a base for all the items IDs.

Type
string

element

Overrides the default element name to apply unique styles with the Customization Provider.

Type
string
Default
HORIZONTAL_TABS" or "VERTICAL_TABS

orientation

Defines the orientation of the composite widget. If the composite has a single row or column (one-dimensional), the orientation value determines which arrow keys can be used to move focus:

  • undefined: all arrow keys work.
  • horizontal: only left and right arrow keys work.
  • vertical: only up and down arrow keys work.

It doesn't have any effect on two-dimensional composites.

Type
Orientation

selectedId

The current selected tab's id.

Type
string

state

When using the state hook to control the tab set your self, the state prop takes the returned state from the hook.

Type
TabStateReturn

variant

Changes each Tab to either equally fit the width of the containing element or hug the contents of its label.

Type
| "fitted" | "inverse" | "inverse_fitted" | "full_width" | "inverse_full_width"

TabList

TabList page anchor

aria-label RequiredRequired

Required label for this Tabs component. Titles the entire Tabbing context for screen readers.

Type
string

element

Overrides the default element name to apply unique styles with the Customization Provider.

Type
string
Default
HORIZONTAL_TAB_LIST" or "VERTICAL_TAB_LIST

variant

Changes each Tab to either equally fit the width of the containing element or hug the contents of its label.

Type
| "fitted" | "inverse" | "inverse_fitted" | "full_width" | "inverse_full_width"

Tab

Tab page anchor

aria-disabled

Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.

Type
Booleanish

disabled

Same as HTML attribute.

Type
boolean

element

Overrides the default element name to apply unique styles with the Customization Provider.

Type
string
Default
HORIZONTAL_TAB" or "VERTICAL_TAB

focusable

When an element is disabled, it may still be focusable. It works similarly to readOnly on form elements. In this case, only aria-disabled will be set.

Type
boolean

id

Same as the HTML attribute.

Type
string

TabPanels

TabPanels page anchor

element

Overrides the default element name to apply unique styles with the Customization Provider.

Type
string
Default
HORIZONTAL_TAB_PANELS" or "VERTICAL_TAB_PANELS

TabPanel

TabPanel page anchor

element

Overrides the default element name to apply unique styles with the Customization Provider.

Type
string
Default
HORIZONTAL_TAB_PANEL" or "VERTICAL_TAB_PANEL

id

Same as the HTML attribute.

Type
string

paddingTop

Removes the default padding from the TabPanel.

Type
"space0"

tabId

The ID of the Tab component this Panel pairs with.

Type
string

UseTabsState

UseTabsState page anchor

TabStateReturn

TabStateReturn page anchor

baseId RequiredRequired

ID that will serve as a base for all the items IDs.

Type
string

down RequiredRequired

Moves focus to the item below.

Type
(unstable_allTheWay?: boolean | undefined) => void

first RequiredRequired

Moves focus to the first item.

Type
() => void

groups RequiredRequired

Lists all the composite groups with their id and DOM ref. This state is automatically updated when registerGroup and unregisterGroup are called.

Type
Group[]

items RequiredRequired

Lists all the composite items with their id, DOM ref, disabled state and groupId if any. This state is automatically updated when registerItem and unregisterItem are called.

Type
Item[]

last RequiredRequired

Moves focus to the last item.

Type
() => void

loop RequiredRequired

On one-dimensional composites:

  • true loops from the last item to the first item and vice-versa.
  • horizontal loops only if orientation is horizontal or not set.
  • vertical loops only if orientation is vertical or not set.
  • If currentId is initially set to null, the composite element will be focused in between the last and first items.

On two-dimensional composites:

  • true loops from the last row/column item to the first item in the same row/column and vice-versa. If it's the last item in the last row, it moves to the first item in the first row and vice-versa.
  • horizontal loops only from the last row item to the first item in the same row.
  • vertical loops only from the last column item to the first item in the column row.
  • If currentId is initially set to null, vertical loop will have no effect as moving down from the last row or up from the first row will focus the composite element.
  • If wrap matches the value of loop, it'll wrap between the last item in the last row or column and the first item in the first row or column and vice-versa.

Type
boolean | Orientation

manual RequiredRequired

Whether the tab selection should be manual.

Type
boolean

move RequiredRequired

Moves focus to a given item ID.

Type
(id: string | null) => void

next RequiredRequired

Moves focus to the next item.

Type
(unstable_allTheWay?: boolean | undefined) => void

panels RequiredRequired

Lists all the panels.

Type
Item[]

previous RequiredRequired

Moves focus to the previous item.

Type
(unstable_allTheWay?: boolean | undefined) => void

registerGroup RequiredRequired

Registers a composite group.

Type
(group: Group) => void

registerItem RequiredRequired

Registers a composite item.

Type
(item: Item) => void

registerPanel RequiredRequired

Registers a tab panel.

Type
(item: Item) => void

reset RequiredRequired

Resets to initial state.

Type
() => void

rtl RequiredRequired

Determines how next and previous functions will behave. If rtl is set to true, they will be inverted. This only affects the composite widget behavior. You still need to set dir="rtl" on HTML/CSS.

Type
boolean

select RequiredRequired

Moves into and selects a tab by its id.

Type
(id: string | null) => void

setBaseId RequiredRequired

Sets baseId.

Type
Dispatch<SetStateAction<string>>

setCurrentId RequiredRequired

Sets currentId. This is different from composite.move as this only updates the currentId state without moving focus. When the composite widget gets focused by the user, the item referred by the currentId state will get focus.

Type
Dispatch<SetStateAction<string | null | undefined>>

setLoop RequiredRequired

Sets loop.

Type
Dispatch<SetStateAction<boolean | Orientation>>

setOrientation RequiredRequired

Sets orientation.

Type
Dispatch<SetStateAction<Orientation | undefined>>

setRTL RequiredRequired

Sets rtl.

Type
Dispatch<SetStateAction<boolean>>

setSelectedId RequiredRequired

Sets selectedId.

Type
Dispatch<SetStateAction<string | null | undefined>>

setShift RequiredRequired

Sets shift.

Type
Dispatch<SetStateAction<boolean>>

setWrap RequiredRequired

Sets wrap.

Type
Dispatch<SetStateAction<boolean | Orientation>>

shift RequiredRequired

Has effect only on two-dimensional composites. If enabled, moving up or down when there's no next item or the next item is disabled will shift to the item right before it.

Type
boolean

sort RequiredRequired

Sorts the composite.items based on the items position in the DOM. This is especially useful after modifying the composite items order in the DOM. Most of the time, though, you don't need to manually call this function as the re-ordering happens automatically.

Type
() => void

unregisterGroup RequiredRequired

Unregisters a composite group.

Type
(id: string) => void

unregisterItem RequiredRequired

Unregisters a composite item.

Type
(id: string) => void

unregisterPanel RequiredRequired

Unregisters a tab panel.

Type
(id: string) => void

unstable_hasActiveWidget RequiredRequired

Type
boolean

unstable_idCountRef RequiredRequired

Type
MutableRefObject<number>

unstable_includesBaseElement RequiredRequired

Type
boolean

unstable_moves RequiredRequired

Stores the number of moves that have been performed by calling move, next, previous, up, down, first or last.

Type
number
Default
0

unstable_setHasActiveWidget RequiredRequired

Sets hasActiveWidget.

Type
Dispatch<SetStateAction<boolean>>

unstable_setIncludesBaseElement RequiredRequired

Sets includesBaseElement.

Type
Dispatch<SetStateAction<boolean>>

unstable_setVirtual RequiredRequired

Sets virtual.

Type
Dispatch<SetStateAction<boolean>>

unstable_virtual RequiredRequired

If enabled, the composite element will act as an aria-activedescendant container instead of roving tabindex. DOM focus will remain on the composite while its items receive virtual focus.

Type
boolean

up RequiredRequired

Moves focus to the item above.

Type
(unstable_allTheWay?: boolean | undefined) => void

wrap RequiredRequired

Has effect only on two-dimensional composites. If enabled, moving to the next item from the last one in a row or column will focus the first item in the next row or column and vice-versa.

  • true wraps between rows and columns.
  • horizontal wraps only between rows.
  • vertical wraps only between columns.
  • If loop matches the value of wrap, it'll wrap between the last item in the last row or column and the first item in the first row or column and vice-versa.

Type
boolean | Orientation