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
- Track (
button.kit-sw,role="switch"): off--ios-off(or#3A3C45on dark), on--ios-on. - Knob (
span.kit-sw-knob,aria-hidden): white, 27px (md) with a soft shadow, slides 20px. - 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
| Prop | Value | Look | When |
|---|---|---|---|
variant | 'ios' (default) | iOS switch, green on | All v3 settings |
variant | 'compact' | 38 × 22, accent on, 16px knob | Dense rows |
size (ios) | 'md' | 51 × 31 | Default outside the shell |
size (ios) | 'sm' | 41 × 25 | PR sidebar (auto inside the shell's sidebar / nav sheet) |
surface (ios) | 'light' | #E9E9EA off track | Cards |
surface (ios) | 'dark' | #3A3C45 off track | Ink surfaces (auto in the sidebar) |
States
| State | Trigger | Look |
|---|---|---|
| Off | checked={false} | Grey track, knob at start |
| On | checked | Green track, knob at end |
| Focus-visible | keyboard | The 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) |
| Disabled | disabled | 60 % opacity, default cursor |
| Motion | toggle | 200ms 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">witharia-checked. Space and Enter toggle it (native button activation); it is in the tab order unlessdisabled. - Name, by type (a switch without one does not compile):
label: the accessible name, asaria-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 (aSettingRowtitle, a heading). Prefer this when the words are already on screen.rowLabelled: inside aKeyValuerow (KeyValueItem.control) the row's label names it through context.
- Description: pass
aria-describedbyfor 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.
Related
SettingRow: title + description + control.DefaultableSetting: a setting that can fall back to TRNDR's default.ChoiceGroup: radio choices.
See also: KeyValue · FormField · SaveBar · SearchBox · Segmented
Source
src/kit/Switch.tsx (line 44) on GitHub.