Tabs

Overview

The Tabs component organizes related content into a set of panels, one of which is visible at a time. It is composed of four recipe parts: useTabsRecipe() for the root wrapper that lays out the bar and the active panel, useTabsListRecipe() for the tab list (role="tablist"), useTabsTriggerRecipe() for each individual tab button (role="tab"), and useTabsContentRecipe() for the content panels (role="tabpanel"). Each composable creates a fully configured recipe with compound variants that handle the color-variant combinations — including the active-tab indicator and dark mode overrides — automatically.

The active tab is matched through the aria-selected attribute, so the selected styling is driven by accessible markup rather than an extra class. The Tabs recipes integrate directly with the default design tokens preset and generate type-safe utility classes at build time with zero runtime CSS.

Why use the Tabs recipe?

The Tabs recipe helps you:

• Ship faster with sensible defaults: Get 3 styles, 3 surfaces, 3 sizes, and 2 orientations out of the box with a single set of composable calls.
• Compose an accessible structure: Four coordinated recipes (root, list, trigger, content) map cleanly onto the tablist / tab / tabpanel roles.
• Maintain consistency: Compound variants ensure every color-variant combination follows the same rules, including the active indicator and dark mode overrides.
• Customize without forking: Override base styles, default variants, or filter out options you don't need — all through the options API.
• Stay type-safe: Full TypeScript support means your editor catches invalid color, variant, size, or orientation values at compile time.
• Integrate with your tokens: Every value references the design tokens preset, so theme changes propagate automatically.

Usage

import { styleframe } from 'virtual:styleframe';
import {
    useTabsRecipe,
    useTabsListRecipe,
    useTabsTriggerRecipe,
    useTabsContentRecipe,
} from '@styleframe/theme';

const s = styleframe();

const tabs = useTabsRecipe(s);
const tabsList = useTabsListRecipe(s);
const tabsTrigger = useTabsTriggerRecipe(s);
const tabsContent = useTabsContentRecipe(s);

export default s;

import { useState } from "react";
import { tabs, tabsList, tabsTrigger, tabsContent } from "virtual:styleframe";

const items = [
    { value: "account", label: "Account" },
    { value: "password", label: "Password" },
];

export function Tabs() {
    const [active, setActive] = useState("account");

    return (
        <div className={tabs({ orientation: "horizontal", size: "md" })}>
            <div role="tablist" className={tabsList({ color: "neutral", variant: "line", size: "md" })}>
                {items.map((item) => (
                    <button
                        key={item.value}
                        type="button"
                        role="tab"
                        aria-selected={active === item.value}
                        className={tabsTrigger({ color: "neutral", variant: "line", size: "md" })}
                        onClick={() => setActive(item.value)}
                    >
                        {item.label}
                    </button>
                ))}
            </div>
            {items.map((item) =>
                active === item.value ? (
                    <div key={item.value} role="tabpanel" className={tabsContent({ size: "md" })}>
                        {item.label} panel
                    </div>
                ) : null,
            )}
        </div>
    );
}

Colors

The Tabs recipe includes 3 color surfaces: light, dark, and neutral. Like the Card recipe, Tabs use neutral-spectrum colors designed for content surfaces rather than status communication. The color controls the list track, the active-tab indicator, and the panel text, combined with every visual style through compound variants — including dark mode overrides.

The neutral color adapts automatically: it uses a light appearance in light mode and a dark appearance in dark mode, making it the safest default for general-purpose tabs.

Color Reference

Variants

Three visual style variants control how the active tab is rendered. Each variant is combined with the selected color through compound variants, so you always get the correct indicator, surface, and text colors for your chosen color.

Line

A colored rule on the active edge (the bottom in horizontal orientation, the inline end in vertical), with a matching track on the list. The classic, low-chrome tabs style and the default.

Pill

A segmented bar: the list sits on a muted, rounded surface and the active tab is raised onto its own surface with a subtle shadow. Matches the shadcn/Radix default look.

Soft

The active tab gets a soft tinted fill with no underline or bar. A gentle style that works well in dense layouts.

Sizes

Three size variants from sm to lg control the trigger's font size and padding, the list gap, and the panel padding.

Size Reference

Orientation

The orientation axis switches between a horizontal tab bar (the default) and a vertical one. In vertical orientation the root places the list beside the panels, the list stacks its triggers, and the line indicator moves from the bottom edge to the inline end.

States

The trigger responds to the standard interactive states:

• Active. The selected trigger is matched through aria-selected="true" and receives the variant's active styling (indicator, surface, or fill). Always set aria-selected on the active tab.
• Hover. Inactive triggers lift toward the emphasis color on hover for affordance.
• Focus. Keyboard focus shows a 2px @color.primary outline ring via :focus-visible. The content panel shows the same ring when focused.
• Disabled. A disabled trigger (<button disabled>) is dimmed to 50% opacity with cursor: not-allowed and ignores pointer events.

Anatomy

The Tabs recipe is composed of four independent recipes that work together:

<!-- All four parts working together -->
<div class="tabs(...)">
    <div role="tablist" class="tabsList(...)">
        <button role="tab" aria-selected="true" class="tabsTrigger(...)">Tab 1</button>
        <button role="tab" aria-selected="false" class="tabsTrigger(...)">Tab 2</button>
    </div>
    <div role="tabpanel" class="tabsContent(...)">Panel 1</div>
</div>

Accessibility

• Use the tab roles. Wrap the triggers in an element with role="tablist", give each trigger role="tab", and give each panel role="tabpanel". Mark the active trigger with aria-selected="true" — the recipe relies on it for the active styling.
• Wire up keyboard navigation. A tablist should support arrow-key movement between tabs, with Home/End jumping to the first/last tab. Set aria-orientation on the list to match the layout.
• Connect triggers and panels. Give each trigger an id and point its aria-controls at the panel, and give each panel aria-labelledby pointing back at its trigger.
• Verify contrast ratios. The dark color places light text on a dark surface. Default tokens meet WCAG AA 4.5:1 contrast. If you override colors, verify with the WebAIM Contrast Checker.

Customization

Overriding Defaults

Each tabs composable accepts an optional second argument to override any part of the recipe configuration. Overrides are deep-merged with the defaults, so you only need to specify what changes:

import { styleframe } from 'virtual:styleframe';
import { useTabsListRecipe, useTabsTriggerRecipe } from '@styleframe/theme';

const s = styleframe();

const tabsList = useTabsListRecipe(s, {
    defaultVariants: {
        color: 'neutral',
        variant: 'pill',
        size: 'md',
        orientation: 'horizontal',
    },
});

const tabsTrigger = useTabsTriggerRecipe(s, {
    defaultVariants: {
        color: 'neutral',
        variant: 'pill',
        size: 'md',
        orientation: 'horizontal',
    },
});

export default s;

Filtering Variants

If you only need a subset of the available variants, use the filter option to limit which values are generated. This reduces the output CSS and keeps your component API focused:

import { styleframe } from 'virtual:styleframe';
import { useTabsTriggerRecipe } from '@styleframe/theme';

const s = styleframe();

// Only generate the neutral color with the line and pill styles
const tabsTrigger = useTabsTriggerRecipe(s, {
    filter: {
        color: ['neutral'],
        variant: ['line', 'pill'],
    },
});

export default s;

API Reference

useTabsRecipe(s, options?)

Creates the root wrapper recipe. Lays out the list and panel and owns the orientation.

Variants:

useTabsListRecipe(s, options?)

Creates the tab list recipe. Paints the line track or the pill container.

Variants:

useTabsTriggerRecipe(s, options?)

Creates the trigger recipe. Renders the active indicator per variant via the aria-selected modifier.

Variants:

useTabsContentRecipe(s, options?)

Creates the content panel recipe with adaptive text color, a focus ring, and size-based padding.

Variants:

Learn more about recipes →

Best Practices

• Always set aria-selected: The active styling is driven by aria-selected="true". Without it, no tab appears selected.
• Pass color, variant, and orientation consistently: The list track and the trigger indicator must share these values to line up.
• Use neutral for general-purpose tabs: It adapts to light and dark mode automatically.
• Pick pill for a segmented control feel: Reserve line for low-chrome navigation and soft for dense layouts.
• Filter what you don't need: If your tabs only use one color, pass a filter option to reduce generated CSS.

FAQ