Rewrote all the docs - more noob friendly now.
Co-authored-by: Copilot <copilot@github.com>
This commit is contained in:
+34
-62
@@ -1,46 +1,22 @@
|
||||
# Switch
|
||||
|
||||
A toggle switch (on/off). Renders as a hidden `<input type="checkbox">` with a styled track and thumb driven by JavaScript. Fires no custom events — read the underlying checkbox value in form submissions.
|
||||
An on/off toggle that looks like a physical light switch. Use it for settings where the effect is immediate or where a simple checked/unchecked checkbox would feel too plain — "Enable notifications", "Dark mode", "Maintenance mode".
|
||||
|
||||
---
|
||||
|
||||
## HTML structure
|
||||
## Quick example
|
||||
|
||||
```
|
||||
label[for={id}].flex.items-center.gap-3.cursor-pointer
|
||||
div.switch-root.relative.w-11.h-6.rounded-full ← outer track
|
||||
input[type=checkbox, id, name, class="sr-only", $$Checked$$] ← hidden; holds true state
|
||||
div.switch-thumb.absolute.top-0.5.left-0.5... ← animated thumb
|
||||
span.text-sm.select-none ← label text (omitted when empty)
|
||||
{label}
|
||||
```csharp
|
||||
new Switch(
|
||||
id: "notifications",
|
||||
label: "Enable notifications",
|
||||
name: "enableNotifications",
|
||||
isChecked: true)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CSS mechanics
|
||||
|
||||
| Class | Effect |
|
||||
|---|---|
|
||||
| `sr-only` | Hides the real checkbox visually but keeps it accessible |
|
||||
| `switch-root` | `bg-input` (off) / `bg-primary` (on) — toggled by JS adding `switch-on` class |
|
||||
| `switch-thumb` | `h-5 w-5 rounded-full bg-background shadow transition-transform` |
|
||||
| `translate-x-5` | Added to thumb by JS when switch is on (slides right) |
|
||||
|
||||
---
|
||||
|
||||
## JavaScript (`initSwitch` in `components.js`)
|
||||
|
||||
Runs on `DOMContentLoaded` and `htmx:afterSwap`.
|
||||
|
||||
**Per-switch initialization:**
|
||||
|
||||
1. Guard `_switchInit` prevents double-binding
|
||||
2. Sync visual state from the hidden checkbox `checked` property on load
|
||||
3. On `label` click: toggle `checked`, toggle `switch-on` on the track, toggle `translate-x-5` on the thumb
|
||||
|
||||
---
|
||||
|
||||
## Constructor signature
|
||||
## All the options
|
||||
|
||||
```csharp
|
||||
public Switch(
|
||||
@@ -50,54 +26,50 @@ public Switch(
|
||||
bool isChecked = false)
|
||||
```
|
||||
|
||||
| Parameter | Description |
|
||||
| Parameter | What it does |
|
||||
|---|---|
|
||||
| `id` | Element id for the hidden checkbox; label's `for` attribute |
|
||||
| `label` | Optional visible text to the right of the toggle |
|
||||
| `name` | Form field name for the hidden checkbox |
|
||||
| `isChecked` | Initial on/off state |
|
||||
| `id` | The element id for the hidden checkbox. |
|
||||
| `label` | Optional text shown to the right of the toggle. |
|
||||
| `name` | Form field name — required if you want the value submitted. |
|
||||
| `isChecked` | Whether the switch is on by default. |
|
||||
|
||||
---
|
||||
|
||||
## Usage examples
|
||||
## Real-world examples
|
||||
|
||||
### Basic on/off toggle
|
||||
### Preferences form with multiple toggles
|
||||
|
||||
```csharp
|
||||
new Switch(
|
||||
id: "notifications",
|
||||
label: "Enable notifications",
|
||||
name: "enableNotifications",
|
||||
isChecked: true)
|
||||
new Switch(id: "email-alerts", label: "Email alerts", name: "emailAlerts", isChecked: prefs.EmailAlerts)
|
||||
new Switch(id: "push-notifs", label: "Push notifications", name: "pushNotifs", isChecked: prefs.PushNotifs)
|
||||
new Switch(id: "weekly-summary", label: "Weekly digest", name: "weeklySummary", isChecked: prefs.WeeklySummary)
|
||||
```
|
||||
|
||||
### Toggle without label
|
||||
|
||||
```csharp
|
||||
new Switch(id: "darkMode", name: "darkMode")
|
||||
```
|
||||
|
||||
### Reading in a form handler
|
||||
Reading on the server:
|
||||
|
||||
```csharp
|
||||
public record Command(
|
||||
[property: FromForm] string? EnableNotifications = null
|
||||
[property: FromForm] string? EmailAlerts = null, // null = off
|
||||
[property: FromForm] string? PushNotifs = null,
|
||||
[property: FromForm] string? WeeklySummary = null
|
||||
);
|
||||
|
||||
bool notificationsOn = command.EnableNotifications != null;
|
||||
bool emailAlerts = command.EmailAlerts != null;
|
||||
```
|
||||
|
||||
> Like all checkboxes, an unchecked switch is not included in the form submission. Use `null` as the default in your command record.
|
||||
> **Important:** Like a checkbox, an unchecked switch is not included in the form submission. Always use `string?` (nullable) with a default of `null`.
|
||||
|
||||
### HTMX auto-save on change
|
||||
### Toggle without a label (e.g. in a table row)
|
||||
|
||||
```csharp
|
||||
// The hidden checkbox is named, so wrap in a form or use hx-include:
|
||||
new Switch(
|
||||
id: "maintenance",
|
||||
name: "maintenanceMode",
|
||||
label: "Maintenance mode",
|
||||
isChecked: currentState)
|
||||
new Switch(id: $"active-{user.Id}", name: "isActive", isChecked: user.IsActive)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How it works
|
||||
|
||||
Switch is a styled `<label>` wrapping a hidden `<input type="checkbox">`. JavaScript in `components.js` listens for clicks and animates the visible track and thumb. The hidden checkbox holds the actual state and is what gets submitted with a form. Because it is a real checkbox under the hood, the form submission behaviour is identical to a plain Checkbox component.
|
||||
```
|
||||
|
||||
```html
|
||||
|
||||
Reference in New Issue
Block a user