Files
basecoat/docs/src/components/switch.mdx
T

116 lines
4.5 KiB
Plaintext
Raw Normal View History

2026-06-17 11:19:31 +08:00
# Switch
<Preview>
<div role="group" class="field flex-row items-center gap-2">
<input type="checkbox" id="airplane-mode" role="switch" class="input" />
<label for="airplane-mode">Airplane Mode</label>
</div>
</Preview>
## Usage
Add `role="switch"` and the `input` class to a native `<input type="checkbox">`. Use a native `<label>` or `aria-label` for accessible naming.
```html
<input type="checkbox" role="switch" class="input" />
```
#### HTML structure
<dl>
<dt><code class="highlight language-html">&lt;input type="checkbox" role="switch" class="input"&gt;</code></dt>
<dd>The switch control. Use native checkbox state: add <code>checked</code> for an initially enabled switch, <code>disabled</code> for a disabled switch, and <code>aria-invalid="true"</code> for invalid state.</dd>
<dt><code>data-size="sm"</code> <span class="badge-secondary">Optional</span></dt>
<dd>Renders the smaller switch size.</dd>
</dl>
## Examples
### Description
<Preview class="w-full max-w-sm">
<div role="group" class="field flex-row items-start justify-between gap-3">
<div class="grid gap-1.5">
<label for="switch-focus-mode">Share across devices</label>
<p id="switch-focus-mode-description" class="field-description">Focus is shared across devices, and turns off when you leave the app.</p>
</div>
<input type="checkbox" id="switch-focus-mode" role="switch" class="input" aria-describedby="switch-focus-mode-description" />
</div>
</Preview>
### Choice Card
Card-style selection where a native `<label>` wraps the entire field for a clickable card pattern.
<Preview class="w-full max-w-md">
<label class="field flex-row items-start justify-between gap-3 rounded-lg border p-4">
<span class="grid gap-1.5">
<span>Share across devices</span>
<span class="field-description">Focus is shared across devices, and turns off when you leave the app.</span>
</span>
<input type="checkbox" role="switch" class="input" checked />
</label>
</Preview>
### Disabled
Use the native `disabled` attribute on the switch and `data-disabled="true"` on the field wrapper when the surrounding field should use disabled styling.
<Preview class="w-full max-w-sm">
<div class="grid gap-4">
<div role="group" class="field flex-row items-center justify-between" data-disabled="true">
<label for="switch-disabled-unchecked">Disabled (Unchecked)</label>
<input type="checkbox" id="switch-disabled-unchecked" role="switch" class="input" disabled />
</div>
<div role="group" class="field flex-row items-center justify-between" data-disabled="true">
<label for="switch-disabled-checked">Disabled (Checked)</label>
<input type="checkbox" id="switch-disabled-checked" role="switch" class="input" checked disabled />
</div>
</div>
</Preview>
### Invalid
Add `aria-invalid="true"` to the switch and `data-invalid="true"` to the field wrapper.
<Preview class="w-full max-w-sm">
<div role="group" class="field flex-row items-start justify-between gap-3" data-invalid="true">
<div class="grid gap-1.5">
<label for="switch-invalid">Accept terms and conditions</label>
<p class="field-error">You must accept the terms and conditions to continue.</p>
</div>
<input type="checkbox" id="switch-invalid" role="switch" class="input" aria-invalid="true" />
</div>
</Preview>
### Size
Use `data-size="sm"` to render the smaller switch size.
<Preview class="w-full max-w-sm">
<div class="grid gap-4">
<div role="group" class="field flex-row items-center justify-between">
<label for="switch-size-sm">Small</label>
<input type="checkbox" id="switch-size-sm" role="switch" class="input" data-size="sm" />
</div>
<div role="group" class="field flex-row items-center justify-between">
<label for="switch-size-default">Default</label>
<input type="checkbox" id="switch-size-default" role="switch" class="input" />
</div>
</div>
</Preview>
## RTL
Switch field layout uses document direction. Set `dir="rtl"` on the field or an ancestor.
<Preview class="w-full max-w-sm">
<div dir="rtl" role="group" class="field flex-row items-start justify-between gap-3">
<div class="grid gap-1.5">
<label for="switch-rtl">المشاركة عبر الأجهزة</label>
<p id="switch-rtl-description" class="field-description">يتم مشاركة التركيز عبر الأجهزة، ويتم إيقاف تشغيله عند مغادرة التطبيق.</p>
</div>
<input type="checkbox" id="switch-rtl" role="switch" class="input" aria-describedby="switch-rtl-description" checked />
</div>
</Preview>