# @data-slot/switch
Headless switch component for vanilla JavaScript. Accessible, form-ready, and unstyled.
## Installation
```bash
npm install @data-slot/switch
```
## Quick Start
```html
```
## API
### Initialization
#### `create(scope?)`
Auto-discover and bind all switch instances in a scope (defaults to `document`).
```typescript
import { create } from "@data-slot/switch";
const controllers = create(); // Returns SwitchController[]
```
#### `createSwitch(root, options?)`
Create a controller for a specific element.
```typescript
import { createSwitch } from "@data-slot/switch";
const controller = createSwitch(element, {
defaultChecked: true,
name: "notifications",
uncheckedValue: "off",
onCheckedChange: (checked) => console.log(checked),
});
```
### Slots
#### Runtime Slots
- `switch` - Root control that toggles the checked state and receives switch semantics, keyboard handling, and form integration.
- `switch-thumb` - Optional visual thumb inside the root; receives checked and disabled state for styling.
#### Markup
```html
```
Use a neutral root element (`span` or `div`) when you want Base UI-style label wrapping and shadcn-like composition. The controller injects a visually hidden checkbox next to the root for form submission, label support, and native validation.
### Data Attributes
JS options take precedence over data attributes on the root element.
| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-default-checked` | `boolean` | `false` | Initial checked state |
| `data-disabled` | `boolean` | `false` | Disable user interaction and form submission |
| `data-read-only` / `data-readOnly` | `boolean` | `false` | Prevent user interaction while keeping the field enabled |
| `data-required` | `boolean` | `false` | Require a checked value |
| `data-name` | `string` | - | Form field name |
| `data-value` | `string` | native checkbox `"on"` | Submitted value when checked |
| `data-unchecked-value` / `data-uncheckedValue` | `string` | - | Submitted value when unchecked |
### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `defaultChecked` | `boolean` | `false` | Initial checked state |
| `disabled` | `boolean` | `false` | Disable user interaction and form submission |
| `readOnly` | `boolean` | `false` | Prevent user interaction while keeping the field enabled |
| `required` | `boolean` | `false` | Require the switch to be checked for native form validation |
| `name` | `string` | - | Form field name |
| `value` | `string` | native checkbox `"on"` | Submitted value when checked |
| `uncheckedValue` | `string` | - | Submitted value when unchecked |
| `onCheckedChange` | `(checked: boolean) => void` | `undefined` | Callback when checked state changes |
### Controller
| Method/Property | Description |
|-----------------|-------------|
| `checked` | Current checked state (readonly `boolean`) |
| `toggle()` | Toggle the checked state |
| `check()` | Set checked to `true` |
| `uncheck()` | Set checked to `false` |
| `setChecked(checked)` | Set the checked state explicitly |
| `destroy()` | Remove listeners and generated inputs |
### Events
#### Outbound Events
```javascript
element.addEventListener("switch:change", (event) => {
console.log(event.detail.checked);
});
```
#### Inbound Events
```javascript
element.dispatchEvent(
new CustomEvent("switch:set", { detail: { checked: true } })
);
```
### Styling
#### State Attributes
The root and thumb expose presence attributes:
- `data-checked`
- `data-unchecked`
- `data-disabled`
- `data-readonly`
- `data-required`
The root also syncs:
- `role="switch"`
- `aria-checked="true|false"`
- `aria-disabled="true"` when disabled
- `aria-readonly="true"` when read-only
- `aria-required="true"` when required
#### Tailwind Example
```html
```
## License
MIT