shaamilahmed/Htmx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrote all the docs - more noob friendly now.

Browse Source 
Co-authored-by: Copilot <copilot@github.com>
This commit is contained in:
Enciphered
2026-05-05 23:55:26 +05:00
parent c1e1f74557
commit b530bb8c97
35 changed files with 2159 additions and 2341 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/Components/Checkbox.md
+60 -74
View File
@@ -1,55 +1,10 @@
# Checkbox
A styled checkbox input with an optional visible label. Uses the `accent-primary` Tailwind class so the checkmark color follows your primary theme color.
A styled checkbox with an optional text label. Use it in forms when you want the user to opt in or out of something — "Remember me", "I agree to the terms", or selecting items in a list.
---
## HTML structure
```
div.flex.items-center.space-x-2
input[type=checkbox, id, name, value, class, $$Checked$$]
label[for={id}] ← omitted when label is empty
{label text}
```
---
## CSS mechanics
| Class | Effect |
|---|---|
| `accent-primary` | Checkmark color follows the `--color-primary` CSS variable |
| `h-4 w-4 rounded` | Consistent 16×16 size with slightly rounded corners |
| `cursor-pointer` | Pointer cursor on label |
| `text-sm font-medium leading-none peer-disabled:opacity-70` | Standard label styling |
---
## Constructor signature
```csharp
public Checkbox(
string id,
string label = "",
string name = "",
string value = "true",
bool @checked = false)
```
| Parameter | Description |
|---|---|
| `id` | Element id and the `for` attribute on the label |
| `label` | Visible text next to the checkbox; omit for a standalone checkbox |
| `name` | Form field name (required when used in a form) |
| `value` | Submitted value when checked (default: `"true"`) |
| `checked` | Pre-checked state |
---
## Usage examples
### Basic opt-in checkbox
## Quick example
```csharp
new Checkbox(
@@ -58,7 +13,54 @@ new Checkbox(
name: "newsletter")
```
### Pre-checked
---
## All the options
```csharp
public Checkbox(
string id,
string label = "",
string name = "",
string value = "true",
bool @checked = false)
```
| Parameter | What it does |
|---|---|
| `id` | The element id. Also used by the `<label for="...">` so clicking the label toggles the box. |
| `label` | Visible text next to the checkbox. Leave empty for a standalone checkbox with no label. |
| `name` | Form field name — required if you want the value submitted with the form. |
| `value` | The string that gets submitted when the box is checked. Defaults to `"true"`. |
| `checked` | Pre-tick the checkbox on render. |
---
## Real-world examples
### Terms and conditions on a registration form
```csharp
new Checkbox(
id: "terms",
label: "I agree to the terms of service",
name: "terms",
value: "accepted")
```
Reading it on the server:
```csharp
public record Command(
[property: FromForm] string? Terms = null // null when unchecked, "accepted" when checked
);
bool agreedToTerms = command.Terms == "accepted";
```
> **Important:** HTML forms only submit checkboxes that are *checked*. An unchecked checkbox sends nothing — the field is simply absent. Always use a nullable string (`string?`) or give it a default of `null`.
### Remember me (pre-ticked by default)
```csharp
new Checkbox(
@@ -68,45 +70,29 @@ new Checkbox(
checked: true)
```
### No visible label
### Multiple checkboxes in a preferences form
```csharp
new Checkbox(id: "select-all", name: "selectAll")
new Checkbox(id: "email-alerts", label: "Email alerts", name: "emailAlerts")
new Checkbox(id: "sms-alerts", label: "SMS alerts", name: "smsAlerts")
new Checkbox(id: "weekly-summary", label: "Weekly summary", name: "weeklySummary")
```
### Custom submitted value
```csharp
new Checkbox(
id: "agree",
label: "I agree to the terms",
name: "terms",
value: "accepted")
```
### Reading in a form handler
Server-side:
```csharp
public record Command(
[property: FromForm] string? Newsletter = null, // null when unchecked
[property: FromForm] string? RememberMe = null
[property: FromForm] string? EmailAlerts = null,
[property: FromForm] string? SmsAlerts = null,
[property: FromForm] string? WeeklySummary = null
);
bool wantsNewsletter = command.Newsletter == "true";
bool rememberUser = command.RememberMe == "true";
```
> Note: Unchecked checkboxes are not included in form data. Always use a nullable string or a default value of `null`.
---
## Tips and tricks
## How it works
- Because HTML forms only submit checked checkboxes, pair a checkbox with a hidden input of the same name and value `"false"` if you need the unchecked state explicitly in your command.
- The label `for` attribute ties to the `id`, so clicking the label text toggles the checkbox — always set `id`.
- If you need multi-select (select multiple rows in a table), use the same `name` for all checkboxes; they will be submitted as a comma-separated list or multiple values depending on form binding.
- `accent-primary` is a modern CSS property — all current browsers support it.
- `accent-primary` is a modern CSS property — all current browsers support it.
Checkbox renders a native `<input type="checkbox">` styled with `accent-primary` so the checkmark colour matches your theme's primary colour. The label is a separate `<label for="{id}">` element — clicking anywhere on the label text toggles the checkbox.
---