Search docs

Tabs

Layered panels of content, one shown at a time.

Tabs follows the Tabs WAI-ARIA design pattern, with automatic or manual activation.

Manage your account details and profile information.
import { component$, useStyles$ } from '@builder.io/qwik';
import { Tabs } from '@leve-ui/tabs';
import styles from './default.css?inline';

export default component$(() => {
  useStyles$(styles);

  return (
    <Tabs.Root defaultValue="tab1" class="tabs-default-root">
      <Tabs.List aria-label="Account settings" class="tabs-default-list">
        <Tabs.Trigger value="tab1" class="tabs-default-trigger">
          Account
        </Tabs.Trigger>
        <Tabs.Trigger value="tab2" class="tabs-default-trigger">
          Password
        </Tabs.Trigger>
        <Tabs.Trigger value="tab3" class="tabs-default-trigger">
          Settings
        </Tabs.Trigger>
      </Tabs.List>
      <Tabs.Content value="tab1" class="tabs-default-content">
        Manage your account details and profile information.
      </Tabs.Content>
      <Tabs.Content value="tab2" class="tabs-default-content">
        Change your password and manage authentication settings.
      </Tabs.Content>
      <Tabs.Content value="tab3" class="tabs-default-content">
        Configure application preferences and notification options.
      </Tabs.Content>
    </Tabs.Root>
  );
});

Installation#

Install the individual package, or use @leve-ui/core to get every component at once:

pnpm add @leve-ui/tabs

Anatomy#

import { Tabs } from '@leve-ui/tabs'; // or '@leve-ui/core'

<Tabs.Root>
  <Tabs.List>
    <Tabs.Trigger />
  </Tabs.List>
  <Tabs.Content />
</Tabs.Root>
PartElementDescription
Tabs.Root<div>Wraps the parts and holds the selected value.
Tabs.List<div>The list of tabs, with role="tablist".
Tabs.Trigger<button>One tab, with role="tab". Selects the Content with the same value. Use as to render another element or component.
Tabs.Content<div>The panel of a tab, with role="tabpanel". Always rendered, and hidden while its tab is not selected.

A component passed to as on Tabs.Trigger must spread the props it receives onto a single element, including id, aria-*, data-*, and on*$ event handlers.

Examples#

Controlled#

bind:value controls the selected tab with a signal. The buttons outside the tabs change it.

External controls:
Panel 1 content (controlled by signal).

Disabled Trigger#

disabled on a Trigger disables that tab. Arrow keys skip it.

Panel 1: Navigating with arrow keys skips the disabled tab.

Manual#

With activationMode="manual", arrow keys only move focus. Press Enter or Space to select the focused tab.

Panel 1: In manual mode, arrow keys move focus without changing the active panel.

Vertical#

orientation="vertical" makes ArrowUp / ArrowDown move between tabs instead of ArrowLeft / ArrowRight. It sets aria-orientation and data-orientation.

Profile details and public information.

API Reference#

Root#

PropDefaultType
defaultValuenullstring | null

The value of the tab selected initially (uncontrolled).

bind:value–Signal<string | null> | Signal<string>

A signal with the value of the selected tab (controlled).

onValueChange$–QRL<(value: string) => void>

Called when the selected tab changes.

orientation'horizontal''horizontal' | 'vertical'

The orientation of the tab list.

activationMode'automatic''automatic' | 'manual'

How a tab is selected. - 'automatic': selected when it receives focus - 'manual': focus moves only; Enter or Space selects

looptrueboolean

Whether arrow keys wrap from the last tab to the first and vice versa.

Also accepts all <div> attributes.

Data attributeValue
data-leve-tabsAlways present
data-orientation"horizontal" | "vertical"

The selected value is uncontrolled with defaultValue, or controlled with bind:value. onValueChange$ is called when the selected tab changes. Give each Trigger and its Content the same value.

List#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-tabs-listAlways present
data-orientation"horizontal" | "vertical"

Trigger#

PropDefaultType
as'button'keyof HTMLElementTagNameMap | Component<any>

The element or component to render instead of <button>. A component must spread the props it receives onto one element.

value (required)–string

A unique value that identifies the tab. Must match the value of its Content.

disabledfalseboolean

Disables the tab.

Also accepts all <button> attributes.

Data attributeValue
data-leve-tabs-triggerAlways present
data-state"active" | "inactive"
data-disabledPresent when disabled
data-orientation"horizontal" | "vertical"

Content#

PropDefaultType
value (required)–string

The value of the Trigger that shows this panel.

Also accepts all <div> attributes.

Data attributeValue
data-leve-tabs-contentAlways present
data-state"active" | "inactive"
data-orientation"horizontal" | "vertical"

The Content has the hidden attribute while its tab is not selected.

Accessibility#

Complies with the Tabs WAI-ARIA design pattern.

  • Name the tab list with aria-label or aria-labelledby on Tabs.List.
  • Tabs.List renders role="tablist" and aria-orientation.
  • Each Tabs.Trigger is a <button type="button"> with role="tab", aria-selected and aria-controls pointing to its Content. Its text content is its accessible name. Disabled tabs use the native disabled attribute, so they are not focusable.
  • Each Tabs.Content renders role="tabpanel" and aria-labelledby pointing to its Trigger. It has tabIndex={0}, so the panel itself can receive focus.
  • Only one tab is in the tab sequence: the selected tab, or the first enabled tab when nothing is selected.

Keyboard Interactions#

KeyDescription
TabMoves focus to the selected tab. When focus is on a tab, moves focus to the selected panel.
ArrowRight / ArrowLeftHorizontal only. Moves focus to the next / previous enabled tab, and selects it in automatic mode. Wraps around when loop is true.
ArrowDown / ArrowUpVertical only. Moves focus to the next / previous enabled tab, and selects it in automatic mode. Wraps around when loop is true.
HomeMoves focus to the first enabled tab, and selects it in automatic mode.
EndMoves focus to the last enabled tab, and selects it in automatic mode.
Enter / SpaceSelects the focused tab (manual mode).

In right-to-left text, ArrowRight and ArrowLeft are reversed.