Tabs

Client componentEngine: react-aria

ImportCopy Anchor Link

import { Tabs } from '@nizivo/react/tabs';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css
import '@nizivo/react/css/tabs.css';

Static or interactiveCopy Anchor Link

Client. It always ships React Aria's tabs code (+38,812 B gzip under Turbopack for one Tabs on the Next.js fixture). When every view is a URL, TabNav does the job with no client code. How to choose.

DirectionCopy Anchor Link

The strip's direction comes from the NizivoConfig scope: under a right-to-left locale (Arabic, Hebrew, Persian and so on) the layout and the arrow keys follow it, and ArrowLeft moves to the next tab. A strip whose direction differs from its locale's sets dir on Tabs.Root, which wins over the scope:

<NizivoConfig locale="de-DE">
  {/* a strip of Arabic labels inside a German page */}
  <Tabs.Root dir="rtl" defaultValue="overview">
    …
  </Tabs.Root>
</NizivoConfig>

dir takes 'ltr' or 'rtl' and is rendered as the root's dir attribute. Without it, nothing is rendered and the nearest Tabs.Root around the strip that sets dir decides, so a strip nested in its panels keys the way CSS lays it out; with none, the locale decides. Nothing reads the page's DOM, so a dir attribute on any other ancestor does not turn the arrows, and 'auto' is not accepted. The override covers the tab list's keys only: the tab labels and the panels keep the scope's locale (a number formatted in a label stays in it), and a Menu, Select or Tooltip inside a panel takes its direction from NizivoConfig.

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { Text } from '@nizivo/react/text';
import { Tabs } from '@nizivo/react/tabs';

const STATUSES = [
  ['all', 'All orders', 'Every order from the last 90 days.'],
  ['unfulfilled', 'Unfulfilled', 'Paid orders that still need to ship.'],
  ['unpaid', 'Unpaid', 'Orders waiting for a payment.'],
  ['open', 'Open', 'Orders with a pending return or exchange.'],
  ['archived', 'Archived', 'Orders you closed.'],
] as const;

export function TabsExample(): JSX.Element {
  return (
    <Tabs.Root defaultValue="all">
      <Tabs.List aria-label="Order status">
        {STATUSES.map(([value, label]) => (
          <Tabs.Tab key={value} value={value}>
            {label}
          </Tabs.Tab>
        ))}
      </Tabs.List>
      {STATUSES.map(([value, , text]) => (
        <Tabs.Panel key={value} value={value}>
          <Text tone="secondary">{text}</Text>
        </Tabs.Panel>
      ))}
    </Tabs.Root>
  );
}

import type { JSX } from 'react';
import { Text } from '@nizivo/react/text';
import { Tabs } from '@nizivo/react/tabs';

/** Stand-ins for `@nizivo/icons` glyphs (16 px Lucide strokes). */
function Package(): JSX.Element {
  return (
    <svg
      viewBox="0 0 24 24"
      width="1em"
      height="1em"
      fill="none"
      stroke="currentColor"
      strokeWidth={1.92}
      strokeLinecap="round"
      strokeLinejoin="round"
    >
      <path d="M21 8 12 3 3 8v8l9 5 9-5zM3 8l9 5 9-5M12 13v8" />
    </svg>
  );
}

function Truck(): JSX.Element {
  return (
    <svg
      viewBox="0 0 24 24"
      width="1em"
      height="1em"
      fill="none"
      stroke="currentColor"
      strokeWidth={1.92}
      strokeLinecap="round"
      strokeLinejoin="round"
    >
      <path d="M2 6h12v10H2zM14 9h4l4 4v3h-8" />
      <circle cx="6" cy="18" r="2" />
      <circle cx="18" cy="18" r="2" />
    </svg>
  );
}

export function TabsStatesExample(): JSX.Element {
  return (
    <Tabs.Root defaultValue="to-pack">
      <Tabs.List aria-label="Fulfilment">
        <Tabs.Tab value="to-pack" icon={<Package />} count={12}>
          To pack
        </Tabs.Tab>
        <Tabs.Tab value="shipped" icon={<Truck />} count={48}>
          Shipped
        </Tabs.Tab>
        <Tabs.Tab value="returns" count={0} disabled>
          Returns
        </Tabs.Tab>
      </Tabs.List>
      <Tabs.Panel value="to-pack">
        <Text tone="secondary">12 orders are ready to pack.</Text>
      </Tabs.Panel>
      <Tabs.Panel value="shipped">
        <Text tone="secondary">48 orders shipped this week.</Text>
      </Tabs.Panel>
      <Tabs.Panel value="returns">
        <Text tone="secondary">No returns.</Text>
      </Tabs.Panel>
    </Tabs.Root>
  );
}

import type { JSX } from 'react';
import { Text } from '@nizivo/react/text';
import { Textarea } from '@nizivo/react/textarea';
import { Tabs } from '@nizivo/react/tabs';

export function TabsManualExample(): JSX.Element {
  return (
    <Tabs.Root defaultValue="write" activationMode="manual">
      <Tabs.List aria-label="Note">
        <Tabs.Tab value="write">Write</Tabs.Tab>
        <Tabs.Tab value="preview">Preview</Tabs.Tab>
      </Tabs.List>
      <Tabs.Panel value="write" keepMounted>
        <Textarea aria-label="Note text" defaultValue="Ship the blue mugs first." />
      </Tabs.Panel>
      <Tabs.Panel value="preview">
        <Text tone="secondary">The preview renders when this tab is selected.</Text>
      </Tabs.Panel>
    </Tabs.Root>
  );
}

Other exportsCopy Anchor Link

TabsActivationMode type

import type { TabsActivationMode } from '@nizivo/react/tabs'

When a tab is selected (WAI-ARIA APG tabs). - automatic: an arrow key moves focus and selects the tab it lands on (the APG default, for panels that show without a noticeable delay); - manual: arrow keys only move focus; Enter or Space selects (for panels that are slow to show).

type TabsActivationMode = "automatic" | "manual"

TabsListProps type

import type { TabsListProps } from '@nizivo/react/tabs'

The props of Tabs.List, listed above.

TabsListState type

import type { TabsListState } from '@nizivo/react/tabs'

The render state of Tabs.List, listed above.

TabsPanelProps type

import type { TabsPanelProps } from '@nizivo/react/tabs'

The props of Tabs.Panel, listed above.

TabsPanelState type

import type { TabsPanelState } from '@nizivo/react/tabs'

The render state of Tabs.Panel, listed above.

TabsRootProps type

import type { TabsRootProps } from '@nizivo/react/tabs'

The props of Tabs.Root, listed above.

TabsRootState type

import type { TabsRootState } from '@nizivo/react/tabs'

The render state of Tabs.Root, listed above.

TabsTabProps type

import type { TabsTabProps } from '@nizivo/react/tabs'

The props of Tabs.Tab, listed above.

TabsTabState type

import type { TabsTabState } from '@nizivo/react/tabs'

The render state of Tabs.Tab, listed above.

TabsValueReason type

import type { TabsValueReason } from '@nizivo/react/tabs'

Why the selected tab changed. React Aria reports no cause, so with it details.reason is always 'unknown' (§9.3 rule 2); the names are the causes an engine that reports one would use.

type TabsValueReason = "tab-press" | "keyboard"

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-tabs, .nz-tabs-count, .nz-tabs-icon, .nz-tabs-label, .nz-tabs-list, .nz-tabs-panel, .nz-tabs-sizer, .nz-tabs-tab, .nz-tabs-text.

AccessibilityCopy Anchor Link

These parts are interactive. Each gets the focus outline and touch-action rule from @nizivo/react/css/base.css (the nz.base layer), so the floor survives a restyle:

• tabs-tab: draws the focus outline itself on keyboard focus.

In forced-colours mode these states keep a visible system colour: tabs-tab[data-selected]::before (fill).

Behaviour comes from the react-aria engine through Nizivo's adapter: focus management, ARIA wiring and keyboard handling are the engine's.

Pattern: WAI-ARIA Authoring Practices.

KeyboardCopy Anchor Link

Source: react-aria-components 1.22.1 Tabs, TabList, Tab and TabPanel (react-aria 3.53.1 useTabList, useTab and useTabPanel) through _engines/react-aria/tabs.client.tsx. The browser lane (test/browser/tabs.spec.tsx) checks Tab entry, arrows, Home, End, wrapping, skipping a disabled tab, manual activation and the RTL flip, and that a dir on Tabs.Root overrides the NizivoConfig scope, that the nearest of nested scopes wins, that a strip nested in a dir root's panel follows that dir, that changing dir turns the arrows without remounting the tabs, and that a server render with dir hydrates without warnings.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: Figma node 7275:14781
• Ghost masters: Figma node 755:961