Skip to Content
BBRICKSv0.7.4
KitPatterns

PillTabs

The mock's .tabs: a pill container with a roving tab stop. Controlled: the screen keeps value in the URL.

import { PillTabs } from '@ergasti/bricks';

Examples

Tabs with counts

Arrow keys move between tabs, Home and End jump; activation="automatic" selects as you move, the default needs Enter or Space.

Code
import { useState } from 'react';
import { PillTabs } from '@ergasti/bricks';

function Counts() {
  const [tab, setTab] = useState('mine');
  return (
    <PillTabs label="Creators" idPrefix="docs-tabs" value={tab} onChange={setTab}>
      <PillTabs.Tab value="mine" count={304}>My creators</PillTabs.Tab>
      <PillTabs.Tab value="requests" count={6} warn>Join requests</PillTabs.Tab>
      <PillTabs.Tab value="invitations" count={17}>Invitations</PillTabs.Tab>
    </PillTabs>
  );
}

Automatic activation

Focus moving to a tab selects it.

Code
import { useState } from 'react';
import { PillTabs } from '@ergasti/bricks';

function Automatic() {
  const [tab, setTab] = useState('live');
  return (
    <PillTabs label="Challenges" idPrefix="docs-tabs-auto" value={tab} onChange={setTab} activation="automatic">
      <PillTabs.Tab value="live">Live</PillTabs.Tab>
      <PillTabs.Tab value="ended">Ended</PillTabs.Tab>
    </PillTabs>
  );
}

Props

Prop

Type

PillTabs.Tab

Prop

Type

Design guidance

How the BRICKS design system uses PillTabs. Written in docs/content/components/PillTabs.md; the props above are read from the code, which wins where the two disagree.

A pill-shaped tab bar with optional counts; use it to switch between the views of one screen (My creators / Join requests / Invitations; Wallet / Orders / Payouts).

It is the mock's .tabs: a white pill container with 1px line, the selected tab filled ink with white text, each count small and dimmed (or a red pill when it needs attention). It hugs its content (it does not stretch). It is controlled: the screen keeps value, usually in the URL. Keyboard follows the WAI tabs pattern with a roving tab stop and manual activation by default.

Anatomy

  1. Tablist: div.kit-tabs[role=tablist], inline-flex, 4px padding and gap, radius 99, --card with --line border, horizontal scroll without scrollbar when too wide.
  2. Tab: button.kit-tab[role=tab], padding 8px 16px, 600 --ink-3; selected: --ink fill, white.
  3. Count (optional): .kit-tab-n, 11px, 70% opacity, dir="ltr"; warn makes it a white-on---bad pill.

Variants

Prop valueLookWhen to use
Tab count"Join requests 6"Views with a size worth knowing.
Tab warnCount in a red pillSomething waits on the user (pending invitations).
activation="manual" (default)Arrows move focus; Enter / Space selectTabs that load data or change the URL.
activation="automatic"Arrows also selectCheap, instant panels (the legacy Tabs).
controlsTabs point to panels (aria-controls)When you render role="tabpanel" panels with PillTabs.panelId.

States

StateTrigger
Selectedvalue === Tab.value: ink fill, aria-selected, tab stop.
No matchvalue matches no tab (a stale URL, a hidden tab): no tab is selected and the first tab takes the tab stop, so Tab still reaches the tablist. Tabs wrapped in other components keep the stop on value.
Hover / pressedpressed scales to 0.98.
Focus-visiblekit focus ring.
Overflowtoo many tabs scroll horizontally.

Types

Helpers: PillTabs.panelId(prefix, value), PillTabs.tabId(prefix, value).

Usage

// Brand › Creators
<PillTabs label="Creators" idPrefix="creators" value={tab} onChange={(t) => setParam('tab', t)}>
  <PillTabs.Tab value="mine" count={304}>My creators</PillTabs.Tab>
  <PillTabs.Tab value="requests" count={6}>Join requests</PillTabs.Tab>
  <PillTabs.Tab value="groups" count={3}>Groups</PillTabs.Tab>
  <PillTabs.Tab value="invitations" count={2} warn>Invitations</PillTabs.Tab>
</PillTabs>
<KpiGrid>…</KpiGrid>
<Card title="My creators">…</Card>
// With real panels
<PillTabs label="Payments" idPrefix="pay" value={tab} onChange={setTab} controls>
  <PillTabs.Tab value="wallet">Wallet</PillTabs.Tab>
  <PillTabs.Tab value="orders">Orders</PillTabs.Tab>
  <PillTabs.Tab value="payouts">Payouts</PillTabs.Tab>
</PillTabs>
<div role="tabpanel" id={PillTabs.panelId('pay', tab)} aria-labelledby={PillTabs.tabId('pay', tab)}>{panel}</div>

Where it appears

  • In the v3 mocks: Brand › Creators tabs with counts (BrandCreators); Brand › Motivation tabs (Challenges / Bonuses / Gifts) (BrandMotivation); Brand › Payments tabs (BrandWallet); PR Portal › list tabs with counts, Approvals status tabs, Affiliate programs Campaigns / Challenges (PrApprovals, PrPrograms, PrCreators).

Guidelines

Do

  • Keep 2–5 tabs with one-word or two-word names.
  • Keep the selected tab in the URL so reload and back work.
  • Use warn only for a count that needs action.

Don't

  • Don't use tabs to filter one list by status; use FilterChips or KPI filter cards.
  • Don't set controls unless every panel id exists.

RTL and Arabic

  • The tablist flows right to left; arrow keys follow the visual order.
  • Counts are dir="ltr". Arabic: "صنّاعي 304", "طلبات الانضمام 6".

Tokens

--card, --line, --ink, --ink-3, --bad, --focus-ring, --min-touch-target.

Accessibility

  • role="tablist" named by label; tabs have aria-selected and one tab stop.
  • ←/→ move (mirrored in RTL), Home / End jump; manual activation by default so a slow view does not load on every arrow.
  • A count is part of the tab's name after a pause: "Join requests, 6" (visually hidden comma), so speech input can say the visible words.

Found in the source

  • Roles in the markup: tabpanel, tab, tablist.
  • ARIA attributes set: aria-label, aria-selected, aria-controls, aria-labelledby.
  • Keys the code handles: ArrowUp, ArrowDown.
  • It moves focus in code.

Read from the component's source and tests. See Accessibility for the patterns the library follows.

See also: Accordion · Card · HeroCard · KeyValue

Source

src/kit/patterns/PillTabs.tsx (line 48) on GitHub.

On this page