@@ -0,0 +1,207 @@
|
||||
# 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.
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
```csharp
|
||||
new Checkbox(
|
||||
id: "newsletter",
|
||||
label: "Subscribe to newsletter",
|
||||
name: "newsletter")
|
||||
```
|
||||
|
||||
### Pre-checked
|
||||
|
||||
```csharp
|
||||
new Checkbox(
|
||||
id: "remember",
|
||||
label: "Remember me",
|
||||
name: "rememberMe",
|
||||
checked: true)
|
||||
```
|
||||
|
||||
### No visible label
|
||||
|
||||
```csharp
|
||||
new Checkbox(id: "select-all", name: "selectAll")
|
||||
```
|
||||
|
||||
### Custom submitted value
|
||||
|
||||
```csharp
|
||||
new Checkbox(
|
||||
id: "agree",
|
||||
label: "I agree to the terms",
|
||||
name: "terms",
|
||||
value: "accepted")
|
||||
```
|
||||
|
||||
### Reading in a form handler
|
||||
|
||||
```csharp
|
||||
public record Command(
|
||||
[property: FromForm] string? Newsletter = null, // null when unchecked
|
||||
[property: FromForm] string? RememberMe = 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
|
||||
|
||||
- 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.
|
||||
|
||||
---
|
||||
|
||||
## Complete page example
|
||||
|
||||
**`Templates/PreferencesPage.htmx`**
|
||||
```html
|
||||
<div class="max-w-md mx-auto py-10">
|
||||
<h1 class="text-2xl font-bold mb-6">Preferences</h1>
|
||||
<form method="post" action="/preferences">
|
||||
$$AntiforgeryToken$$
|
||||
<div class="space-y-4 mb-6">
|
||||
$$NewsletterCheck$$
|
||||
$$MarketingCheck$$
|
||||
$$RememberCheck$$
|
||||
</div>
|
||||
$$SaveBtn$$
|
||||
</form>
|
||||
$$SuccessAlert$$
|
||||
</div>
|
||||
```
|
||||
|
||||
**`Templates/PreferencesPage.htmx.cs`**
|
||||
```csharp
|
||||
namespace Htmx.ApiDemo.Templates;
|
||||
|
||||
public sealed class PreferencesPage : PreferencesPageBase
|
||||
{
|
||||
private readonly IHtmxComponent _newsletter;
|
||||
private readonly IHtmxComponent _marketing;
|
||||
private readonly IHtmxComponent _remember;
|
||||
private readonly IHtmxComponent _save;
|
||||
private readonly IHtmxComponent _success;
|
||||
private readonly byte[] _afToken;
|
||||
|
||||
public PreferencesPage(
|
||||
IAntiforgery af,
|
||||
HttpContext ctx,
|
||||
UserPrefs? prefs = null,
|
||||
bool saved = false)
|
||||
{
|
||||
var tokens = af.GetAndStoreTokens(ctx);
|
||||
_afToken = $"""<input type="hidden" name="{tokens.FormFieldName}" value="{tokens.RequestToken}">""".ToUtf8Bytes();
|
||||
|
||||
_newsletter = new Components.Checkbox(
|
||||
id: "newsletter", label: "Receive newsletter",
|
||||
name: "newsletter", @checked: prefs?.Newsletter ?? false);
|
||||
_marketing = new Components.Checkbox(
|
||||
id: "marketing", label: "Receive marketing emails",
|
||||
name: "marketing", @checked: prefs?.Marketing ?? false);
|
||||
_remember = new Components.Checkbox(
|
||||
id: "remember", label: "Keep me signed in",
|
||||
name: "remember", @checked: prefs?.Remember ?? false);
|
||||
_save = new Components.Button("Save preferences", type: "submit");
|
||||
_success = saved
|
||||
? new Components.Alert(title: "Preferences saved.")
|
||||
: HtmxEmpty.Instance;
|
||||
}
|
||||
|
||||
protected override void RenderAntiforgeryToken(HtmxRenderContext ctx) => ctx.Writer.WriteUtf8(_afToken);
|
||||
protected override void RenderNewsletterCheck(HtmxRenderContext ctx) => _newsletter.Render(ctx.Next());
|
||||
protected override void RenderMarketingCheck(HtmxRenderContext ctx) => _marketing.Render(ctx.Next());
|
||||
protected override void RenderRememberCheck(HtmxRenderContext ctx) => _remember.Render(ctx.Next());
|
||||
protected override void RenderSaveBtn(HtmxRenderContext ctx) => _save.Render(ctx.Next());
|
||||
protected override void RenderSuccessAlert(HtmxRenderContext ctx) => _success.Render(ctx.Next());
|
||||
}
|
||||
```
|
||||
|
||||
**POST handler**
|
||||
```csharp
|
||||
[Handler]
|
||||
[MapPost("/preferences")]
|
||||
public static partial class PostPreferencesHandler
|
||||
{
|
||||
public record Command(
|
||||
[property: FromForm] string? Newsletter = null,
|
||||
[property: FromForm] string? Marketing = null,
|
||||
[property: FromForm] string? Remember = null);
|
||||
|
||||
private static Task<IResult> HandleAsync(
|
||||
[AsParameters] Command cmd, HttpContext ctx, IAntiforgery af, CancellationToken ct)
|
||||
{
|
||||
var prefs = new UserPrefs(
|
||||
Newsletter: cmd.Newsletter != null,
|
||||
Marketing: cmd.Marketing != null,
|
||||
Remember: cmd.Remember != null);
|
||||
// Persist prefs…
|
||||
return ctx.WriteHtmxPage(new PreferencesPage(af, ctx, prefs, saved: true), title: "Preferences");
|
||||
}
|
||||
}
|
||||
|
||||
public record UserPrefs(bool Newsletter, bool Marketing, bool Remember);
|
||||
```
|
||||
|
||||
**`AppJsonSerializerContext.cs`**
|
||||
```csharp
|
||||
[JsonSerializable(typeof(PostPreferencesHandler.Command), TypeInfoPropertyName = "PreferencesCommand")]
|
||||
```
|
||||
Reference in New Issue
Block a user