Tabs

Installation

npx gbs-add-block@latest -a Tabs -beta

The block copies the tabs folder into your project, along with the small shared folder that every component imports. You own the code and can change it freely. There are no peer dependencies other than React.

Requirements

• React 19.2 and @types/react 19.2 (for <Activity>)
• TypeScript target ES2022 or newer, with "jsx": "react-jsx"
• Browsers from 2024 or newer (the styles use light-dark() and color-mix())

Import the stylesheet once, for example in your global CSS:

@import "../components/tabs/styles.css";

or in your root layout / entry file:

import "@/components/tabs/styles.css";

Tabs switch between related views in the same place: a settings page, a record's sections, a dashboard's periods. They follow the WAI-ARIA tabs pattern. There's one stop in the tab order, the arrow keys move between tabs, and disabled tabs are skipped. They come in three looks (an underline, pills or an enclosed segmented control), horizontal or vertical, with a sliding indicator. Hidden panels can keep their state — typed input, scroll position — using React's <Activity>.

Default

Quick Start

"use client";
 
import { Tab, TabList, TabPanel, Tabs } from "@/components/tabs";
 
export default function Project() {
  return (
    <Tabs defaultValue="overview">
      <TabList aria-label="Project">
        <Tab value="overview">Overview</Tab>
        <Tab value="activity" badge={3}>Activity</Tab>
        <Tab value="settings">Settings</Tab>
      </TabList>
 
      <TabPanel value="overview"><Overview /></TabPanel>
      <TabPanel value="activity"><ActivityFeed /></TabPanel>
      <TabPanel value="settings"><SettingsForm /></TabPanel>
    </Tabs>
  );
}

Tabs are controlled with value + onValueChange, or uncontrolled with defaultValue. Without either, the first enabled tab is selected.

Props Table

Tabs

Accepts every <div> attribute, plus:

TabList

Accepts every <div> attribute. Give it aria-label or aria-labelledby.

Tab

Accepts every <button> attribute, plus:

TabPanel

Accepts every <div> attribute, plus:

Keeping Panel State

By default, only the selected panel's content is rendered. That keeps pages light, but a half-filled form in a hidden tab loses its input when you switch away.

<Tabs defaultValue="details" keepMounted>

With keepMounted, hidden panels stay mounted inside React's <Activity mode="hidden">:

• State survives: component state and DOM state (typed text, scroll position) are kept.
• Hidden panels cost little: their effects are cleaned up while hidden and run again when shown, so subscriptions and timers don't keep running in the background.
• Updates are deferred: hidden panels render at low priority, so they don't slow down the visible one.

Use it per panel for the ones that need it: <TabPanel value="form" keepMounted>.

Variants and Orientation

<Tabs variant="line" />                                 {/* underline, the default */}
<Tabs variant="pills" />                                {/* filled background on the selected tab */}
<Tabs variant="enclosed" />                             {/* segmented control */}
<Tabs orientation="vertical" variant="pills" />         {/* a settings sidebar */}

The indicator slides between tabs and follows size changes, for example when a badge count changes. Horizontal tab lists that don't fit scroll sideways, and keyboard focus scrolls the focused tab into view.

Keyboard

Accessibility: role="tablist", role="tab" and role="tabpanel" with aria-selected, aria-controls and aria-labelledby wired up. Only the selected tab is in the tab order (roving tabindex), and panels are focusable so keyboard users can reach content without links or buttons. Disabled tabs use aria-disabled, so they're still announced.

Use activation="manual" when showing a panel is slow (it fetches data, for example), so moving through tabs with the arrows doesn't load each one.

Styling and Theming

All rules are in the CSS components layer, so utility classes passed through className override them.

<TabList className="gap-6" />
<Tab className="uppercase tracking-wide" value="…" />

CSS variables

Override them on .tb-root, on :root, or through style. Each variable falls back to the shared --gbs-* of the same name, then to the DataGrid's --dg-* when that stylesheet is loaded, and finally to the built-in palette.

Data attributes

Headless Use

Next.js

The components are client components with "use client" at the top of their files. They render the selected tab on the server. Before hydration, the line variant marks the selected tab with a static underline, and the sliding indicator takes over once measured.

To keep the selected tab in the URL, control it from search params:

const searchParams = useSearchParams();
const router = useRouter();
 
<Tabs value={searchParams.get("tab") ?? "overview"} onValueChange={(tab) => router.replace(`?tab=${tab}`)}>

Notes

• A value that matches no tab selects the first enabled tab.
• Nested <Tabs> work; each list only moves between its own tabs.
• There's no previous tabs component, so there's nothing to migrate.