Toggle Group

Preview

Installation

pnpm add @oshon-ai/components @oshon-ai/tokens @oshon-ai/primitives

pnpm dlx @oshon-ai/cli add togglegroup

Wire the tokens into your Tailwind v4 stylesheet:

/* app/globals.css */
@import 'tailwindcss';
@import '@oshon-ai/tokens/css';
@import '@oshon-ai/tokens/tailwind';

New here? Walk through the full setup — prereqs, theming, your first render.

Usage

Import the component and render it. Every component supports the standard tier, size, and disabled props where applicable.

'use client';
import { ToggleGroup } from '@oshon-ai/components';

export default function Example() {
  return <ToggleGroup />;
}

<ToggleGroup size="m" ariaLabel="View" defaultValue="week" items={[
          { value: 'day', label: 'Day' },
          { value: 'week', label: 'Week' },
          { value: 'month', label: 'Month' },
        ]} />

<div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', alignItems: 'flex-start' }}>
      <div key="xs" data-story-size="xs">
        <ToggleGroup size="xs" ariaLabel="View" defaultValue="week" items={[
              { value: 'day', label: 'Day' },
              { value: 'week', label: 'Week' },
              { value: 'month', label: 'Month' },
            ]} />
      </div>
      <div key="s" data-story-size="s">
        <ToggleGroup size="s" ariaLabel="View" defaultValue="week" items={[
              { value: 'day', label: 'Day' },
              { value: 'week', label: 'Week' },
              { value: 'month', label: 'Month' },
            ]} />
      </div>
      <div key="m" data-story-size="m">
        <ToggleGroup size="m" ariaLabel="View" defaultValue="week" items={[
              { value: 'day', label: 'Day' },
              { value: 'week', label: 'Week' },
              { value: 'month', label: 'Month' },
            ]} />
      </div>
      <div key="l" data-story-size="l">
        <ToggleGroup size="l" ariaLabel="View" defaultValue="week" items={[
              { value: 'day', label: 'Day' },
              { value: 'week', label: 'Week' },
              { value: 'month', label: 'Month' },
            ]} />
      </div>
      <div key="mobile" data-story-size="mobile">
        <ToggleGroup size="mobile" ariaLabel="View" defaultValue="week" items={[
              { value: 'day', label: 'Day' },
              { value: 'week', label: 'Week' },
              { value: 'month', label: 'Month' },
            ]} />
      </div>
    </div>

Styling

Three layers of customization, in order of escape-hatch strength: className overrides → data-attribute targeting → CSS custom properties.

Passing Tailwind classes

Every Oshon component accepts a className prop merged AFTER the component's default classes. Use it to override spacing, color, or size without forking the component.

<ToggleGroup
  className="ring-2 ring-offset-2 ring-blue-500"
/>

Data attributes

Oshon components expose their internal state as data-oshon-* attributes so you can target them from CSS without coupling to internal class names. The most common attributes are listed below — see the component's source for the full set.

/* Target the secondary tier specifically */
[data-oshon-tier="secondary"] {
  --oshon-color-primary-700: var(--my-brand-color);
}

Interactive states

Every interactive component supports the standard CSS pseudo- classes plus Tailwind's state variants. Focus rings always use :focus-visible so keyboard users see them but mouse users don't.

• :hover / hover:* — pointer hover
• :focus-visible / focus-visible:* — keyboard focus
• :active / active:* — pressed
• :disabled / disabled:* — set via the disabled prop

Anatomy

The named regions a consumer composes when rendering this component. Each is documented separately so you can target keyboard nav, ARIA labels, and slot props with precision.

Keyboard

Accessibility

Every Oshon component ships axe-clean. We test in CI on every PR and publish the audit log per component.

WCAG level

2.2 AA

Screen readers tested

VoiceOver (macOS), NVDA (Windows)

Last axe audit

2026-04-30

Do / Don't

<ToggleGroup
  ariaLabel="View"
  items={[
    { value: 'day',   label: 'Day'   },
    { value: 'week',  label: 'Week'  },
    { value: 'month', label: 'Month' },
  ]}
  defaultValue="week"
  onChange={(v) => setView(v)}
/>

<ToggleGroup
  type="multiple"
  ariaLabel="Text style"
  items={[
    { value: 'b', icon: <BoldIcon />,      ariaLabel: 'Bold'      },
    { value: 'i', icon: <ItalicIcon />,    ariaLabel: 'Italic'    },
    { value: 'u', icon: <UnderlineIcon />, ariaLabel: 'Underline' },
  ]}
  defaultValue={['b']}
/>

<ToggleGroup
  variant="separated"
  ariaLabel="Sort"
  items={[
    { value: 'asc',  label: '↑ Ascending'  },
    { value: 'desc', label: '↓ Descending' },
  ]}
  defaultValue="asc"
/>

<ToggleGroup
  ariaLabel="Plan"
  items={[
    { value: 'free',       label: 'Free' },
    { value: 'pro',        label: 'Pro' },
    { value: 'enterprise', label: 'Enterprise', disabled: true },
  ]}
/>

<ToggleGroup type="single" items={[/* mix of mutually-exclusive AND independent options */]} />

<ToggleGroup style={{ width: 320 }} items={items} />

<ToggleGroup items={tenDifferentValues} />

<ToggleGroup items={[{ value: 'home' }, { value: 'about' }, { value: 'contact' }]} />

Related

• Toggle
• ChoiceChip
• Tabs
• Dropdown
• Button

Design rationale

A toggle group sits at the intersection of three established WAI-ARIA patterns — RadioGroup (single + arrow nav), pressed-button toolbar (multiple), and segmented control (visual). Rather than expose a compound API (`<ToggleGroup><ToggleGroup.Item />`) we follow the Breadcrumbs / WidgetTrendList convention of a single prop-driven items array — easier to type, easier to memoize, no provider plumbing. The two visual variants (`segmented` / `separated`) cover the bulk of the design landscape while a single five-size axis keeps the typography density consistent with the rest of Oshon. Uncontrolled-first matches `Toggle`, `Checkbox`, and every other Phase 4 stateful control: pass `value` to drive externally, ignore it to let the component own the state.