@custmaz/switch-toggle-buttons
v0.1.0
Published
Accessible React switch and single-select toggle button components with CSS-variable theming
Maintainers
custmazReadme
A streamlined UI component library for switches and multi-option toggle groups in React.
React Switch & Toggle Buttons
Two focused UI controls:
Switch (Binary Toggle)
- iOS-style binary toggle
- Supports text or icons in track and thumb
widthMode="auto"prevents label clipping- Horizontal and vertical layouts
- No layout shift during animation
Toggle Button Group
- Single-select (radio-group behavior)
- Supports text and/or icons
- Horizontal and vertical layouts
- Unlimited items
Shared Features
- Fully controlled (no hidden state)
- Accessible (ARIA compliant)
- CSS-variable theming (no CSS-in-JS)
- No runtime styling
- SSR safe
Designed for dashboards and settings-heavy UIs where predictability matters.
Why This Library?
- Content-aware sizing (
widthMode="auto") prevents label clipping - Fully controlled, predictable state
- CSS-variable theming (no runtime styles)
- Layout-safe animations (no shift)
- SSR safe
Installation
npm install @custmaz/switch-toggle-buttonsImport default styles:
import '@custmaz/switch-toggle-buttons/styles.css';Basic Usage
Switch (Two-way)
import { useState } from 'react';
import { Switch } from '@custmaz/switch-toggle-buttons';
export default function Example() {
const [enabled, setEnabled] = useState(false);
return (
<Switch
checked={enabled}
onCheckedChange={setEnabled}
aria-label="Enable notifications"
/>
);
}With track & thumb content
<Switch
checked={enabled}
onCheckedChange={setEnabled}
widthMode="auto"
trackContent={{
off: 'Disabled',
on: 'Enabled',
}}
thumbContent="✓"
/>
ToggleButtons (Multi-option)
import { useState } from 'react';
import { ToggleButtons, ToggleButtonItem } from '@custmaz/switch-toggle-buttons';
export default function LayoutToggle() {
const [layout, setLayout] = useState('grid');
return (
<ToggleButtons value={layout} onValueChange={setLayout}>
<ToggleButtonItem value="grid">Grid</ToggleButtonItem>
<ToggleButtonItem value="list">List</ToggleButtonItem>
</ToggleButtons>
);
}
Vertical layout
<ToggleButtons value={mode} onValueChange={setMode} orientation="vertical">
<ToggleButtonItem value="write">Write</ToggleButtonItem>
<ToggleButtonItem value="preview">Preview</ToggleButtonItem>
<ToggleButtonItem value="split">Split</ToggleButtonItem>
</ToggleButtons>
Customisation & Theming
This library is CSS-first, fully controlled via CSS variables:
- No CSS-in-JS
- No runtime style injection
- No global resets
- Easy dark mode integration
All styling is controlled through CSS variables.
Example: global theme
:root {
--tb-bg-track: #e5e7eb;
--tb-bg-track-active: #6366f1;
--tb-bg-thumb: #ffffff;
--tb-bg-thumb-active: #111827;
--tb-text-inactive: #4b5563;
--tb-text-active: #111827;
--tb-radius-pill: 9999px;
--tb-transition-medium: 250ms cubic-bezier(0.4, 0, 0.2, 1);
}
Per-component overrides
.my-switch {
--tb-bg-track-active: #ff6b6b;
--tb-bg-thumb: #ffffff;
}
.my-toggle-group {
--tb-bg-track: #f0f0f0;
--tb-text-active: #ff3b30;
}
Dark mode example
<body data-theme="dark">[data-theme="dark"] {
--tb-bg-track: #2a2a2a;
--tb-bg-track-active: #818cf8;
--tb-bg-thumb: #1f1f1f;
--tb-text-active: #ffffff;
}Render Props
ToggleButtonItem supports render props for more control over icons or content:
<ToggleButtonItem value="grid">
{(isActive) => (
<>
<GridIcon color={isActive ? 'var(--tb-text-active)' : 'var(--tb-text-inactive)'} />
<p>Grid</p>
</>
)}
</ToggleButtonItem>This is optional. If you just pass children, the component will compute the active state internally.
Accessibility
Accessibility is built-in and follows standard ARIA patterns.
Switch
role="switch"aria-checkedreflects state- Keyboard support (Enter/Space)
aria-orientationsupported (horizontal/vertical)aria-labelrequired if no visible label
Toggle Button Group
role="radiogroup"on containerrole="radio"per item- Full keyboard navigation:
- Arrow keys navigate
- Space/Enter selects
- Home/End jump bounds
Follows WAI-ARIA radio group behavior. No custom or non-standard key bindings.
Maintainer
Maintained solely by the author. External contributions may be considered.
See the Changelog for details on versions and updates.
Issues
Report bugs or request features on GitHub:
https://github.com/custmaz/switch-toggle-buttons/issues
License
MIT