Skip to Content
BBRICKSv0.7.4
KitForms

Switch

An on/off setting: a real button with role=switch; the knob's travel flips in RTL (kit.css).

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

Examples

iOS switch

label is the accessible name; use id and aria-describedby to tie it to your own label and hint text.

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

function Ios() {
  const [gifts, setGifts] = useState(true);
  const [gate, setGate] = useState(true);
  return (
    <div style={{ display: 'grid', gap: 14 }}>
      <label style={{ display: 'flex', gap: 12, alignItems: 'center' }}><Switch label="Creators can pick gifts" checked={gifts} onChange={setGifts} />Creators can pick gifts</label>
      <span style={{ display: 'flex', gap: 12, alignItems: 'center', flexWrap: 'wrap' }}>
        <Switch id="docs-gate" aria-describedby="docs-gate-hint" label="Requests need approval" checked={gate} onChange={setGate} />
        <label htmlFor="docs-gate">Requests need approval</label>
        <span id="docs-gate-hint" className="kit-muted">You approve each join request before the creator gets a coupon.</span>
      </span>
      <Switch label="Disabled" checked disabled onChange={() => {}} />
    </div>
  );
}

Compact

The small 38 × 22 track for dense rows.

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

function Compact() {
  const [on, setOn] = useState(true);
  return <label style={{ display: 'flex', gap: 12, alignItems: 'center' }}><Switch variant="compact" label="Payout requests" checked={on} onChange={setOn} />Payout requests</label>;
}

Sizes and surfaces

size="sm" is the PR mock's sidebar switch (41 × 25); surface="dark" gives the off track the sidebar's #3A3C45 for an ink background. Left out, the surroundings decide: inside the shell's sidebar or nav sheet a switch is small and dark with no prop at all, elsewhere it is the 51 × 31 light switch.

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

function SizesAndSurfaces() {
  const [a, setA] = useState(false);
  const [b, setB] = useState(true);
  const [c, setC] = useState(false);
  const [d, setD] = useState(true);
  return (
    <div style={{ display: 'grid', gap: 14 }}>
      <span style={{ display: 'flex', gap: 16, alignItems: 'center', flexWrap: 'wrap' }}>
        <Switch label="Medium, light" checked={a} onChange={setA} />
        <Switch label="Small, light" size="sm" checked={b} onChange={setB} />
      </span>
      <span style={{ display: 'flex', gap: 16, alignItems: 'center', flexWrap: 'wrap', padding: 14, borderRadius: 18, background: '#141414', color: '#FFFFFF' }}>
        <Switch label="Small, dark" size="sm" surface="dark" checked={c} onChange={setC} />
        <Switch label="Medium, dark" surface="dark" checked={d} onChange={setD} />
        <span style={{ fontSize: 12 }}>On an ink panel</span>
      </span>
    </div>
  );
}

Naming a switch

A switch must have a name, and the type checks it: label when no words are visible, aria-labelledby when a visible heading or label already says it (no words repeated), and rowLabelled inside a KeyValue row's control, where the row's label names it. A switch with none of the three does not compile.

Code
import { useState } from 'react';
import { KeyValue, Switch } from '@ergasti/bricks';

function Naming() {
  const [sms, setSms] = useState(true);
  const [pick, setPick] = useState(false);
  return (
    <div style={{ display: 'grid', gap: 14, maxWidth: 460 }}>
      <span style={{ display: 'flex', gap: 12, alignItems: 'center', justifyContent: 'space-between' }}>
        <span id="docs-sms-title" style={{ fontWeight: 700 }}>SMS when a payout is sent</span>
        <Switch aria-labelledby="docs-sms-title" checked={sms} onChange={setSms} />
      </span>
      <KeyValue items={[{ label: 'Creators can pick gifts', control: <Switch rowLabelled checked={pick} onChange={setPick} /> }]} />
    </div>
  );
}

Props

Prop

Type

Design guidance

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

An on/off toggle for a setting that applies at once; use it in settings rows and rule cards.

Switch is a real <button role="switch"> with aria-checked. The default ios look is the v3 mock's 51 × 31 iOS switch, green when on; compact is the 0.1.0 38 × 22 accent switch for dense rows. The type forces a name: label, aria-labelledby or rowLabelled (named by the KeyValue row it sits in); a switch without one does not compile. The knob's travel flips in RTL.

Anatomy

  1. Track (button.kit-sw, role="switch"): off --ios-off (or #3A3C45 on dark), on --ios-on.
  2. Knob (span.kit-sw-knob, aria-hidden): white, 27px (md) with a soft shadow, slides 20px.
  3. Touch hit area (::after): at least 44px on touch screens (≤1024px); on desktop the hit area is the track itself (51 × 31, 41 × 25 or 38 × 22).

Variants

PropValueLookWhen
variant'ios' (default)iOS switch, green onAll v3 settings
variant'compact'38 × 22, accent on, 16px knobDense rows
size (ios)'md'51 × 31Default outside the shell
size (ios)'sm'41 × 25PR sidebar (auto inside the shell's sidebar / nav sheet)
surface (ios)'light'#E9E9EA off trackCards
surface (ios)'dark'#3A3C45 off trackInk surfaces (auto in the sidebar)

States

StateTriggerLook
Offchecked={false}Grey track, knob at start
OncheckedGreen track, knob at end
Focus-visiblekeyboardThe shared kit ring: outline: none; box-shadow: var(--focus-ring) (the shared rule comes last in kit.css and wins over the switch's own outline rule)
Disableddisabled60 % opacity, default cursor
Motiontoggle200ms track and knob transition (off under reduced motion)

Usage

A settings row:

<SettingRow title="Let creators pick their gift" description="Creators choose from your gift products in the app"
  control={<Switch label="Let creators pick their gift" checked={rules.pick} onChange={(pick) => setRules({ ...rules, pick })} />} />

In a KeyValue row:

<KeyValue items={[{ key: 'payouts', label: 'Payout requests', control: <Switch rowLabelled checked={on} onChange={setOn} /> }]} />

Named by a visible heading:

<h3 id="auto-approve">Auto-approve new creators</h3>
<Switch aria-labelledby="auto-approve" checked={auto} onChange={setAuto} />

Where it appears

  • Brand › Motivation › Gifts › "Gift rules" card ("Set by the TRNDR team", drawn read-only: the switches are dimmed and do not respond).
  • PR Portal › Brands › Brand detail › "Gift rules" (switch rows: "Creators can pick gifts", one gift per creator, cooldown).
  • PR Portal › sidebar › "Show decision tags" (the small dark switch, DecisionsCard; a review aid in the mock).
  • Screens: Motivation, PR · Brand.

Guidelines

Do

  • Use it only for changes that apply immediately; use a checkbox in forms that save later.
  • Keep the visible label and the accessible name the same words.

Don't

  • Don't put "On"/"Off" text beside it.
  • Don't use it for choosing between two named options (use Segmented).

RTL and Arabic

  • Knob travel is reversed under [dir='rtl'] (--kit-sw-travel-rtl), so "on" is at the inline end.

Tokens

--ios-on, --ios-off, --kit-sw-w, --kit-sw-h, --kit-sw-knob, --kit-sw-travel, --kit-sw-travel-rtl, --kit-sw-off, --color-accent, --color-surface-card (compact), --rasp (focus), --radius-full.

Accessibility

  • Element and role: a native <button type="button" role="switch"> with aria-checked. Space and Enter toggle it (native button activation); it is in the tab order unless disabled.
  • Name, by type (a switch without one does not compile):
    • label: the accessible name, as aria-label. Keep a visible label beside it that says the same words, so speech-input users can say what they see.
    • aria-labelledby: point at the id of a visible label (a SettingRow title, a heading). Prefer this when the words are already on screen.
    • rowLabelled: inside a KeyValue row (KeyValueItem.control) the row's label names it through context.
  • Description: pass aria-describedby for a hint or an error under the row; it is read after the name and state.
  • State is announced as "on" / "off" (switch semantics), never only by colour: the knob position also changes.
  • Focus: the shared kit ring (--focus-ring), not an outline.
  • Disabled: disabled (60 % opacity), removed from the tab order. For a read-only setting someone must still reach and hear, show the value as text instead.
  • Hit area: 44px on touch screens (≤1024px) through ::after.
  • Motion: the 200ms knob slide turns off under reduced motion.

Found in the source

  • Roles in the markup: switch.
  • ARIA attributes set: aria-checked, aria-label, aria-labelledby, aria-describedby, aria-hidden.
  • Its tests cover: “is a named role=switch button that flips on click and with the keyboard”.

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

See also: KeyValue · FormField · SaveBar · SearchBox · Segmented

Source

src/kit/Switch.tsx (line 44) on GitHub.

On this page