Skip to main content

​
Overview

Off
On
Disabled off
Disabled on
Switch is used for settings that take immediate effect when toggled — no form submission needed. Unlike Checkbox, a Switch implies an instant action rather than a selection to be submitted.

​
Installation

npm install @araf-ds/core

​
Usage

import { Switch } from "@araf-ds/core"

export default function Example() {
  return (
    <Switch label="Enable dark mode" />
  )
}

​
Variants

​
Basic

Enable dark mode
<Switch label="Enable dark mode" />

​
On by Default

Email notifications
<Switch label="Email notifications" defaultChecked />

​
With Description

Auto-save
Automatically save your work every 5 minutes.
<Switch
  label="Auto-save"
  description="Automatically save your work every 5 minutes."
  defaultChecked
/>

​
Label on Left

Show sidebar
<Switch label="Show sidebar" labelPosition="left" />

​
Disabled

Beta features
Always-on feature
<Switch label="Beta features" disabled />
<Switch label="Always-on feature" disabled defaultChecked />

​
Controlled

const [enabled, setEnabled] = useState(false);

<Switch
  checked={enabled}
  onCheckedChange={setEnabled}
  label="Maintenance mode"
/>

​
API Reference

​
checked
boolean
Controlled checked state.
​
defaultChecked
boolean
default:"false"
Uncontrolled initial state.
​
onCheckedChange
(checked: boolean) => void
Callback fired when the switch state changes.
​
label
string
Label text displayed next to the switch.
​
description
string
Supporting description shown below the label.
​
labelPosition
string
default:"right"
Position of the label relative to the switch. Values: left · right
​
disabled
boolean
default:"false"
Disables the switch and applies the disabled visual style.
​
className
string
Additional Tailwind classes for custom overrides.

​
Accessibility

  • Switch uses role="switch" with aria-checked for proper screen reader announcement
  • Label is associated via htmlFor / id — clicking the label also toggles the switch
  • description is linked via aria-describedby
  • disabled uses the native disabled attribute, removing the element from tab order
  • Space bar toggles the switch when focused — follows ARIA switch pattern
  • Focus ring meets WCAG 2.1 AA contrast requirements

​
Do’s & Don’ts

Do

  • Use Switch for settings that take immediate effect (dark mode, notifications)
  • Always provide a descriptive label — never a switch alone
  • Use description to clarify the impact of toggling
  • Place switches in settings panels or preference pages

Don't

  • Don’t use Switch inside a form that requires submission — use Checkbox instead
  • Don’t use Switch for multi-select scenarios — use Checkbox Group
  • Don’t use ambiguous labels like “On/Off” — describe what is being toggled
  • Don’t disable without explaining why in nearby helper text