Tabs

01Preview

Change the controls to try every supported combination. The preview renders the real component, the code updates with it, and the arrow keys work inside the tab bar.

import { Tabs, TabsContent, TabsList, TabsTrigger } from '@nuton/ui'
import { RiBookOpenLine, RiFileList3Line, RiGroupLine, RiLayoutGridLine } from '@remixicon/react'

<Tabs defaultValue="overview">
  <TabsList aria-label="Biology 101 sections">
    <TabsTrigger value="overview" leadingIcon={<RiLayoutGridLine />}>Overview</TabsTrigger>
    <TabsTrigger value="assignments" leadingIcon={<RiFileList3Line />} count={3} countLabel="3 to mark">Assignments</TabsTrigger>
    <TabsTrigger value="lessons" leadingIcon={<RiBookOpenLine />}>Lessons</TabsTrigger>
    <TabsTrigger value="students" leadingIcon={<RiGroupLine />}>Students</TabsTrigger>
  </TabsList>
  <TabsContent value="overview"><p>Biology 101 has 12 lessons, 28 students and 3 assignments to mark this week.</p></TabsContent>
  <TabsContent value="assignments"><p>Three assignments are waiting to be marked: the cell diagram, the microscope lab and the weekly quiz.</p></TabsContent>
  <TabsContent value="lessons"><p>Cell structure is next, followed by Photosynthesis and Respiration.</p></TabsContent>
  <TabsContent value="students"><p>28 students are enrolled in this space, and 4 joined this week.</p></TabsContent>
</Tabs>

02Installation

1. Add the packages

pnpm add @nuton/ui @nuton/tokens @remixicon/react

npm install @nuton/ui @nuton/tokens @remixicon/react

yarn add @nuton/ui @nuton/tokens @remixicon/react

Peer dependencies: react and react-dom 18 or later. Tabs are built on Radix Tabs, which @nuton/ui installs for you. @remixicon/react supplies the icons you pass to triggers (D1).

2. Load tokens and component styles once

// app/layout.tsx (or your app's entry file)
import '@nuton/tokens/tokens.css' // --nu-* design tokens
import '@nuton/ui/styles.css'     // component styles (uses the tokens)

The components are client components ('use client'). You can render them from a server component, but pass onValueChange only from a client component.

03Usage

import { Tabs, TabsContent, TabsList, TabsTrigger } from '@nuton/ui'

export function SpaceSections() {
  return (
    <Tabs defaultValue="lessons">
      <TabsList aria-label="Biology 101 sections">
        <TabsTrigger value="lessons">Lessons</TabsTrigger>
        <TabsTrigger value="students">Students</TabsTrigger>
        <TabsTrigger value="resources">Resources</TabsTrigger>
      </TabsList>
      <TabsContent value="lessons">12 lessons in this space.</TabsContent>
      <TabsContent value="students">28 students enrolled.</TabsContent>
      <TabsContent value="resources">Slides, readings and lab sheets.</TabsContent>
    </Tabs>
  )
}

• Four parts: Tabs holds the state, TabsList is the bar, TabsTrigger is one tab and TabsContent is its panel. Match each trigger and panel with the same value.
• Set defaultValue for uncontrolled tabs, or value with onValueChange when the selected tab lives in your state or the URL.
• Give TabsList an aria-label that names the set, such as “Biology 101 sections”.
• Labels are one or two words in sentence case: “Lessons”, “Lab sheets”. Keep 2–6 tabs, as in Figma.
• Inactive panels aren't rendered (Radix default). Keep form drafts in state above Tabs, or pass forceMount and hide the panel yourself.

04Variants and sizes

Tabs have one look and one size. What changes is the content of each trigger: a label, plus an optional leading icon, count badge and trailing icon, and an optional action at the end of the bar.

Label only

<Tabs defaultValue="lessons">
  <TabsList aria-label="Space sections, label only">
    <TabsTrigger value="lessons">Lessons</TabsTrigger>
    <TabsTrigger value="students">Students</TabsTrigger>
    <TabsTrigger value="resources">Resources</TabsTrigger>
  </TabsList>
  <TabsContent value="lessons"><p>12 lessons in this space.</p></TabsContent>
  <TabsContent value="students"><p>28 students enrolled.</p></TabsContent>
  <TabsContent value="resources"><p>Slides, readings and lab sheets.</p></TabsContent>
</Tabs>

Icons

leadingIcon is Figma's Left icon (20px). It turns State/Primary/Base on the active tab. trailingIcon is Figma's Right icon: an 18px icon in a 20px round frame that stays Icon/Sub-600 in every state. Both are decorative and hidden from screen readers.

<Tabs defaultValue="overview">
  <TabsList aria-label="Space sections with icons">
    <TabsTrigger value="overview" leadingIcon={<RiLayoutGridLine />}>Overview</TabsTrigger>
    <TabsTrigger value="lessons" leadingIcon={<RiBookOpenLine />}>Lessons</TabsTrigger>
    <TabsTrigger value="students" leadingIcon={<RiGroupLine />} trailingIcon={<RiArrowRightSLine />}>
      Students
    </TabsTrigger>
  </TabsList>
  <TabsContent value="overview"><p>A summary of the space.</p></TabsContent>
  <TabsContent value="lessons"><p>12 lessons in this space.</p></TabsContent>
  <TabsContent value="students"><p>28 students enrolled.</p></TabsContent>
</Tabs>

The trailing icon is decoration only. A trigger can't open a menu, so don't use a chevron to suggest one.

Count badge

count is Figma's Number: a 16px red badge after the label. It's part of the tab's name, so a screen reader hears “Assignments 3”. Add countLabel to say what the number means; it replaces the number in the name.

<Tabs defaultValue="assignments">
  <TabsList aria-label="Space sections with counts">
    <TabsTrigger value="assignments" count={3} countLabel="3 to mark">Assignments</TabsTrigger>
    <TabsTrigger value="lessons">Lessons</TabsTrigger>
    <TabsTrigger value="students">Students</TabsTrigger>
  </TabsList>
  <TabsContent value="assignments"><p>3 assignments to mark.</p></TabsContent>
  <TabsContent value="lessons"><p>12 lessons in this space.</p></TabsContent>
  <TabsContent value="students"><p>28 students enrolled.</p></TabsContent>
</Tabs>

Bar action

action is Figma's Button option: one control at the end of the bar. It's rendered outside the tab list, because a tab list may only contain tabs, so it's reached with Tab, not the arrow keys.

<Tabs defaultValue="lessons">
  <TabsList
    aria-label="Space sections with an action"
    action={
      <Button iconOnly size="sm" appearance="stroke" aria-label="Add lesson">
        <RiAddLine />
      </Button>
    }
  >
    <TabsTrigger value="lessons">Lessons</TabsTrigger>
    <TabsTrigger value="students">Students</TabsTrigger>
  </TabsList>
  <TabsContent value="lessons"><p>12 lessons in this space.</p></TabsContent>
  <TabsContent value="students"><p>28 students enrolled.</p></TabsContent>
</Tabs>

Figma draws a 24px compact button here. @nuton/ui has no 24px button, so the closest is a small icon-only Button (36 × 36), which fits the 48px bar. A compact button size is pending a decision.

Sizes

Sizes come from the component CSS, which was checked against Figma's geometry (bar 48, item gap 6, text gap 4, 24 between tabs). Figma centres the 2px active line on the bar's bottom edge, so it spills 1px outside. Code draws it inside the trigger so the scrolling tab list doesn't clip it, a 1px difference pending a decision.

Narrow screens

Figma doesn't say what happens when tabs don't fit. In code the tabs scroll sideways inside the bar, never the page, and the focused tab scrolls into view as the arrow keys move. This preview limits the width so the six tabs scroll.

<Tabs defaultValue="overview">
  <TabsList aria-label="Space sections, scrolling">
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="assignments">Assignments</TabsTrigger>
    <TabsTrigger value="lessons">Lessons</TabsTrigger>
    <TabsTrigger value="students">Students</TabsTrigger>
    <TabsTrigger value="resources">Resources</TabsTrigger>
    <TabsTrigger value="settings">Settings</TabsTrigger>
  </TabsList>
  <TabsContent value="overview"><p>A summary of the space.</p></TabsContent>
  <TabsContent value="assignments"><p>3 assignments to mark.</p></TabsContent>
  <TabsContent value="lessons"><p>12 lessons in this space.</p></TabsContent>
  <TabsContent value="students"><p>28 students enrolled.</p></TabsContent>
  <TabsContent value="resources"><p>Slides, readings and lab sheets.</p></TabsContent>
  <TabsContent value="settings"><p>Space name and who can join.</p></TabsContent>
</Tabs>

05States and interactions

State tokens

Set on .nu-tabs. Override them on a wrapper only for a documented exception.

06Composition examples

Space sections

The main navigation inside a space: icons for quick scanning, a count where something needs attention, and an action for the most common task.

<Tabs defaultValue="overview">
  <TabsList
    aria-label="Biology 101"
    action={
      <Button iconOnly size="sm" appearance="stroke" aria-label="Space settings">
        <RiSettings3Line />
      </Button>
    }
  >
    <TabsTrigger value="overview" leadingIcon={<RiLayoutGridLine />}>Overview</TabsTrigger>
    <TabsTrigger value="lessons" leadingIcon={<RiBookOpenLine />}>Lessons</TabsTrigger>
    <TabsTrigger value="assignments" leadingIcon={<RiFileList3Line />} count={3} countLabel="3 to mark">
      Assignments
    </TabsTrigger>
  </TabsList>
  <TabsContent value="overview"><p>12 lessons, 28 students and a quiz due on Friday.</p></TabsContent>
  <TabsContent value="lessons"><p>Cell structure is next, followed by Photosynthesis.</p></TabsContent>
  <TabsContent value="assignments"><p>Three submissions are waiting to be marked.</p></TabsContent>
</Tabs>

Controlled tabs

Hold the value in state when something outside the tab bar changes the tab, or when the tab should be kept in the URL.

const [tab, setTab] = useState('overview')

<Tabs value={tab} onValueChange={setTab}>
  <TabsList aria-label="Cell structure lesson">
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="notes">Notes</TabsTrigger>
    <TabsTrigger value="quiz">Quiz</TabsTrigger>
  </TabsList>
  <TabsContent value="overview">
    <p>Cells are the basic unit of life. …</p>
    <Button size="sm" appearance="stroke" trailingIcon={<RiArrowRightSLine />} onClick={() => setTab('quiz')}>
      Take the quiz
    </Button>
  </TabsContent>
  <TabsContent value="notes">…</TabsContent>
  <TabsContent value="quiz">…</TabsContent>
</Tabs>

Manual activation

By default a tab opens as soon as it's focused. When a panel is slow to load, set activationMode="manual": the arrow keys move focus only, and Enter or Space opens the panel.

<Tabs defaultValue="week" activationMode="manual" onValueChange={loadProgress}>
  <TabsList aria-label="Progress period">
    <TabsTrigger value="week">This week</TabsTrigger>
    <TabsTrigger value="term">This term</TabsTrigger>
    <TabsTrigger value="all">All time</TabsTrigger>
  </TabsList>
  <TabsContent value="week">…</TabsContent>
  <TabsContent value="term">…</TabsContent>
  <TabsContent value="all">…</TabsContent>
</Tabs>

Tabs or links?

Tabs switch panels on the same page. When each section is its own page with its own URL, use links instead, so they can be opened in a new tab and announced as links. Use Breadcrumbs to show where a page sits, and Button group to switch the view of the same content, such as list and grid.

07API reference

Props

Tabs (Radix Root): holds the selected value.

TabsList: the bar and its tablist.

TabsTrigger: one tab.

TabsContent: the panel for one tab.

Types are exported as TabsProps, TabsListProps, TabsTriggerProps and TabsContentProps. The Radix props are listed in full in the Radix Tabs reference; Nuton adds only action, barClassName, leadingIcon, trailingIcon, count and countLabel (ADR 0005).

Styling hooks

The parts render .nu-tabs, .nu-tabs-bar (with data-has-action), .nu-tabs-list, .nu-tabs-trigger and .nu-tabs-content. Radix sets data-state="active" or "inactive", data-disabled and data-orientation. Use props rather than styling these; the --nu-tabs-* tokens (see State tokens) are the supported override points.

Accessibility

You must: give TabsList an aria-label or aria-labelledby; give the action its own accessible name; add countLabel when a bare number isn't clear; use links, not tabs, for separate pages.

Figma mapping

Nodes: 259:14003 (page), 259:14079 (bar), 259:14119 (item). The bar binds remote 01-Tokens colours; code uses the local twins with the same values (the C19 principle).

08Guidelines and related components

Do and don't

Common mistakes

• Leaving TabsList without an aria-label, so screen readers announce an unnamed tab list.
• Giving a trigger and its panel different values, so the panel never shows.
• Keeping a form draft inside an inactive panel. It unmounts and the draft is lost; lift the state up or use forceMount.
• Putting buttons or links inside TabsList children. Only triggers belong there; use action for a control.

Related components

• Button groupSwitch the view of the same content, such as list and grid.
• BreadcrumbsShow where a page sits in the hierarchy.
• BadgeCounts and status labels outside a tab bar.
• Dropdown menuOverflow for sections that don’t fit as tabs.