--- title: "Checkbox" description: "A box that toggles between checked and not checked, with sizes, states and every field feature." url: "https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/checkbox" section: "Components" --- # Checkbox A box that toggles between checked and not checked, with sizes, states and every field feature. ```html
``` A [toggle](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/toggle) is a button that switches something on or off on the spot. A checkbox is part of a form: it takes a `name` and a `value`, submits with the rest, and is reset by the form. ## Usage - Add `.checkbox` to a native ``. Everything else is plain HTML: `checked`, `required`, `name`, `value`, `disabled`. - Wrap it in a [field](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/field) with `.field-horizontal`: the box first, then `.field-content` holding the `.field-label` and an optional `.field-description`. The label is clickable, so give it the `for` that matches the box's `id`. - Put related boxes in a `
` with a ``, so a screen reader announces the group's question. - A `required` checkbox must be checked to submit, and its label gets the field's asterisk. ```html
Notifications

When someone @mentions you.

``` ## Sizes `.checkbox-sm` and `.checkbox-lg` match the heights of `.input-sm` and `.input-lg`. ```html
``` ## States ### Disabled `disabled` fades the box; inside a field the label and description fade with it. ```html

Available on the Pro plan.

``` ### Error, warning, success Set `aria-invalid="true"` for an error, which turns the border red and the field's label with it, or add `.checkbox-warning` or `.checkbox-success` for the softer states. Pair each with a [field message](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/field#messages) linked with `aria-describedby`. ```html

You must accept the terms to continue.

Highly recommended for admin accounts.

Done.

``` ## Partly selected A box that controls a group is **indeterminate** when some, but not all, of its children are checked. The state is a DOM property rather than an attribute, so markup it with `data-indeterminate`: a small behaviour sets it on load, paints a dash instead of the tick, and clears it when you click the box. ```html
Services to monitor
``` Nothing checks the children for you: that is server state, so keep the box in step in your own code, or read the children on `change` and set the property: ```js app.js const all = document.querySelector("#all"); const children = [...document.querySelectorAll("[data-child]")]; const sync = () => { const checked = children.filter((box) => box.checked).length; all.indeterminate = checked > 0 && checked < children.length; all.checked = checked === children.length; }; all.addEventListener("change", () => children.forEach((box) => (box.checked = all.checked))); children.forEach((box) => box.addEventListener("change", sync)); ``` ## With htmx Checkboxes submit like any other input, so trigger on `change` and send the state in `hx-vals`: ```html

``` ## Nunjucks macro If your templates use Nunjucks, the `checkbox` macro writes the field markup, with the description optional and every attribute passed through `attrs`: ```jinja page.html {% from "components/checkbox/checkbox.html" import checkbox %} {{ checkbox("terms", "I accept the terms", required=true) }} {{ checkbox("digest", "Weekly digest", description="A summary every Monday.", checked=true) }} {{ checkbox("alerts", "Deploy alerts", size="sm", state="warning", attrs='hx-post="/api/settings"') }} ``` ## Reference | Class / attribute | Description | | --- | --- | | `.checkbox` | Native checkbox. Take checked, name, value, required and disabled as usual. | | `.checkbox-sm / -lg` | Matches the height of .input-sm / .input-lg. | | `data-indeterminate` | Paints the mixed state (behaviour: checkbox.ts); cleared when the box is clicked. | | `aria-invalid="true"` | Error border, and a red label in a field. So does :user-invalid. | | `.checkbox-warning / -success` | Warning or success border. | | `checkbox(id, label, …)` | Macro: the whole field. description, checked, indeterminate, disabled, required, size, state, attrs. |