> ## Documentation Index
> Fetch the complete documentation index at: https://araf.badr.co.id/llms.txt
> Use this file to discover all available pages before exploring further.
# Switch
> A toggle control for binary on/off settings that take immediate effect — supports labels, descriptions, and disabled state.
## 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
```bash npm theme={null}
npm install @araf-ds/core
```
```bash yarn theme={null}
yarn add @araf-ds/core
```
```bash pnpm theme={null}
pnpm add @araf-ds/core
```
***
## Usage
```tsx theme={null}
import { Switch } from "@araf-ds/core"
export default function Example() {
return (
)
}
```
***
## Variants
### Basic
Enable dark mode
```tsx theme={null}
```
### On by Default
Email notifications
```tsx theme={null}
```
### With Description
Auto-save
Automatically save your work every 5 minutes.
```tsx theme={null}
```
### Label on Left
Show sidebar
```tsx theme={null}
```
### Disabled
Beta features
Always-on feature
```tsx theme={null}
```
### Controlled
```tsx theme={null}
const [enabled, setEnabled] = useState(false);
```
***
## API Reference
Controlled checked state.
Uncontrolled initial state.
Callback fired when the switch state changes.
Label text displayed next to the switch.
Supporting description shown below the label.
Position of the label relative to the switch. Values: `left` · `right`
Disables the switch and applies the disabled visual style.
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
* 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 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