Playground
A checkbox with a pixel box and a label, for a yes or no that belongs in a form. It keeps a local checked, emits sb-change when the user flips it, and follows the command contract, so it can drive a command as it is. For several choices under one name, use sb-checkbox-group.
Examples
Basic
<div style="display: grid; justify-items: start">
<sb-checkbox label="Shields" checked></sb-checkbox>
<sb-checkbox label="Cloaking device"></sb-checkbox>
<sb-checkbox label="Self-destruct" disabled></sb-checkbox>
</div>
Mixed
indeterminate shows a dash: the server says "some", for example when some of the items below are checked and others aren't. It is the server's view state, not a value. A click resolves it to checked, and the server's next indeterminate wins again.
<sb-checkbox label="All cargo bays" indeterminate></sb-checkbox>
Two-way binding
The live state is the checked property, so data-bind works with the __prop and __event modifiers. Declare the signal first. If it can be true when the page loads and the checkbox sits in a region the server morphs, add data-preserve-attr="checked" (see sb-toggle's Two-way binding).
<div data-signals:_beacon="false">
<sb-checkbox label="Distress beacon" data-bind:_beacon__prop.checked__event.change></sb-checkbox>
<p data-text="$_beacon ? 'Beacon on' : 'Beacon off'"></p>
</div>
With commands
Give it a name, and it emits sb-change with { name, value } when the user flips it (value is the checked state): ready to post as a command. With confirm, it sets :state(pending) until the server's re-rendered checked matches, and revert() goes back to the server's state when a command never reaches the server (an error status, or retries-failed).
<sb-checkbox name="beacon" confirm label="Distress beacon"
data-on:sb-change="@post('/cmd/beacon', {payload: {tabid: $tabid, ...evt.detail}})"
data-on:datastar-fetch="evt.detail.el === el && ['error', 'retries-failed'].includes(evt.detail.type) && el.revert()"></sb-checkbox>
Style the wait from the page:
sb-checkbox:state(pending) { opacity: 0.7; }
The server's word is the checked attribute, by presence, as on a native checkbox: adding it checks the box and removing it clears it, also after the user's click, while the same markup again leaves that click alone. In templ that is checked?={ on }. Any value means checked, checked="false" too, as in HTML: leave the attribute out for not checked. indeterminate is the server's too: a new one wins, a removed one clears the dash, and revert() brings back both. The live state before the echo and the pending state live in local signals and are never reflected to attributes. See Commands and components and the Showcase.
Refusals without page code: give it rev, a number the server bumps with every command it answers for this field, applied or refused (a counter in the tab's state will do; templ: Rev: sb.Int(n)). A new rev makes the server's checked win even when it is unchanged, so a refused click goes back and :state(pending) ends, without a revert() from the page; the same rev again changes nothing. When both change in one morph, the new state applies once. It also brings back the server's indeterminate, like revert(). The page's op ids (see Commands and components) do the same for every component; rev needs nothing on the page. rev only helps where the server renders the outcome into this element's own frame. A view rendered once for every tab, and an outcome no command records (a rate limit, a failed request, being offline), need revert() instead: see When rev is enough.
Pending from the page: pending is the page's word that a command is on its way. While the attribute is there, the component has :state(pending) and aria-busy (on its ElementInternals, so morphs keep them), whatever confirm says: data-attr:pending="$_saving", with a signal the page sets when it sends and the server's answer clears. The two add up: removing pending leaves an unconfirmed edit pending, and revert() leaves the page's pending. In a region the server morphs, a signal-driven pending needs data-preserve-attr="pending".
Forms
Inside a <form>, sb-checkbox submits like a native checkbox: name=value while it is checked (value defaults to on), nothing when it isn't, nothing without a name or while disabled. The mixed state doesn't change what is submitted. new FormData(form) and Datastar's contentType: 'form' include it, and a form reset brings back the server's state without change events. It is not a form-associated element yet (Rocket can't declare one), so required and validity, <fieldset disabled>, <label for> and the form attribute don't reach it. With commands, sb-change carries { name, value } (see With commands).
Styling
Parts: base (the clickable row), box and label. A checked box is --sb-brand in a --sb-brand-light frame with a --sb-text-on-brand mark; an empty one is --sb-control-bg in --sb-control-border (--sb-control-border-hover under the pointer, on a --sb-surface-hover row). The label is --sb-control-text at 0.875rem in the page's font. The corners come from --sb-notch, so [data-sb-style="smooth"] rounds them instead. A disabled checkbox has :state(disabled), from the decoded prop, never from :host([disabled]).
<sb-checkbox label="Gold plating" checked style="--sb-brand: #F5C451; --sb-brand-light: #FFE08A; --sb-text-on-brand: #1B1300"></sb-checkbox>
Accessibility
The row is a role="checkbox" with aria-checked (mixed for the dash) and one tab stop; Space checks and clears it. A disabled checkbox has aria-disabled and leaves the tab order. The label names it. Without one, give <sb-checkbox> an aria-label: the box takes it over (aria-labelledby doesn't reach inside). In forced colours (Windows High Contrast) the checked box uses the system's Highlight colour and the mark HighlightText.
Installation
Add Datastar with Rocket and the Starbase autoloader once per page, then use the tag: the autoloader imports each component the first time its tag appears, including tags a Datastar morph adds later. The Datastar here is v1.0.5 with Starbase's patches. The components also run on the official v1.0.4 and v1.0.5.
<script type="importmap">
{ "imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" } }
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/autoloader.js"></script>
<sb-checkbox name="shields" label="Shields"></sb-checkbox>No flash of undefined elements: put class="sb-cloak" on <html> and add .sb-cloak :not(:defined) { visibility: hidden } to your CSS. The autoloader removes the class once the page's components are defined.
Load just this component, pinned to this version: all its modules in one minified file with its integrity hash, so the browser refuses it if a single byte changes.
<script type="importmap">
{
"imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" },
"integrity": {
"https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js": "sha384-AfXVdZ/qxhMEHK4Nz/pJT6jl9xm3HGMBLBtC9yRuU5A7AQtXHYC0x6ap034vDqBV"
}
}
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/checkbox@0bcb3b6e7a6b/checkbox.bundle.min.js" integrity="sha384-U0N5H931BLzoscOE/13W0EXV4TWlcrm3WKxI7sSwJDQ+as5X98GpKQvgeYu8N9sW"></script>
<sb-checkbox name="shields" label="Shields"></sb-checkbox>Or the minified module files (one file, which the browser requests as it finds their imports), each pinned in the import map:
<script type="importmap">
{
"imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" },
"integrity": {
"https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js": "sha384-AfXVdZ/qxhMEHK4Nz/pJT6jl9xm3HGMBLBtC9yRuU5A7AQtXHYC0x6ap034vDqBV",
"https://starbase.zweiundeins.gmbh/c/checkbox@0bcb3b6e7a6b/checkbox.min.js": "sha384-mOwn3Nd2cOIWJEbZ39JNjczFZIonB8DNN7HNSUkEcwCU0cSykGR7yZcz4PoYRoif"
}
}
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/checkbox@0bcb3b6e7a6b/checkbox.min.js" integrity="sha384-mOwn3Nd2cOIWJEbZ39JNjczFZIonB8DNN7HNSUkEcwCU0cSykGR7yZcz4PoYRoif"></script>
<sb-checkbox name="shields" label="Shields"></sb-checkbox>In production, pin today's whole catalog: its autoloader and an import map with integrity hashes, so the browser refuses any file that changed. This map covers Datastar and this component; importmap.json has the hashes of every component, to merge into yours.
<script type="importmap">
{
"imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" },
"integrity": {
"https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js": "sha384-AfXVdZ/qxhMEHK4Nz/pJT6jl9xm3HGMBLBtC9yRuU5A7AQtXHYC0x6ap034vDqBV",
"https://starbase.zweiundeins.gmbh/c/checkbox@0bcb3b6e7a6b/checkbox.bundle.min.js": "sha384-U0N5H931BLzoscOE/13W0EXV4TWlcrm3WKxI7sSwJDQ+as5X98GpKQvgeYu8N9sW"
}
}
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/@81f24b268adb/autoloader.js" integrity="sha384-bWIhsIq9SpNUiIZyG/lv190MgHA05m8BVYA3LyIoE/pgOF3NUt0437e++4Ht1NcS"></script>
<sb-checkbox name="shields" label="Shields"></sb-checkbox>Components import only datastar and their own files, so copying is enough: save each component's one file (and a file it loads on first use, keeping its folder), and point the import map at your own copy of datastar-rocket.js (the /js/ paths stand for yours).
<sb-checkbox>checkbox.bundle.min.jsone file 1.9 kB brotli
<script type="importmap">
{ "imports": { "datastar": "/js/datastar-rocket.js" } }
</script>
<script type="module" src="/js/checkbox/checkbox.bundle.min.js"></script>
<sb-checkbox name="shields" label="Shields"></sb-checkbox>Or copy the module files, keeping each component's folder, and load each component's module:
<script type="importmap">
{ "imports": { "datastar": "/js/datastar-rocket.js" } }
</script>
<script type="module" src="/js/checkbox/checkbox.min.js"></script>
<sb-checkbox name="shields" label="Shields"></sb-checkbox>In Go, render it with its typed templ wrapper: one field per prop, generated from the component's manifest (the module's README has the type rules). Add the module:
go get github.com/zweiundeins/starbase/templ@latestThen load it, pinned with integrity hashes to the versions the module was generated with, and use it:
// In <head>: the components you list, pinned,
@sb.Imports(sb.ImportsProps{Components: []sb.Tag{sb.TagCheckbox}})
// or the autoloader, which also loads tags a morph adds later: @sb.Imports(sb.ImportsProps{})
// or, around the content of <body>, the components it renders: @sb.Tracked(sb.ImportsProps{}) { … }
@sb.Checkbox(sb.CheckboxProps{Name: "shields", Label: "Shields"})Size
A page loads this component as one file, its bundle, compressed the way it is served (gzip -9, brotli -11): brotli is what it downloads. Datastar and Rocket are shared by every component and not counted.
| File | Original | gzip | brotli |
|---|---|---|---|
checkbox.bundle.min.js | 4.8 kB | 2.2 kB | 1.9 kB |
As module files: one request, 1.8 kB minified with brotli
For a page that loads the module files as they are, requesting each one as it finds its import, or bundles them itself. Each file compressed on its own; the minified one is what the page downloads, and the readable source is always there too.
| File | Original | gzip | brotli | minified |
|---|---|---|---|---|
checkbox.js | 10.7 kB | 4.2 kB | 3.6 kB | 1.8 kB |
API reference
Props
| Attribute | Type | Default | Description |
|---|---|---|---|
checked | boolean | false | Checked when present. The server's word: adding or removing the attribute wins over a local edit, identical markup keeps it; the live state is the checked property. |
indeterminate | boolean | false | Shows the mixed state (the server says "some"). A click resolves it to checked; the live state is the indeterminate property. |
label | string | "" | Visible label next to the box, and its accessible name. |
disabled | boolean | false | Disable interaction. |
name | string | "" | Name reported in sb-change (e.g. the field of a command), and the field it submits in a form. |
value | string | "on" | What a form submits under name while checked, like a native checkbox. |
confirm | boolean | false | Server-confirmed value: :state(pending) while the local state differs from the server's checked attribute (see revert()). |
rev | number | 0 | Revision of the server's value, for commands: the server bumps it with every command it answers for this field, applied or refused. A new rev makes the checked attribute win (present or not) even when it is unchanged, so a refused edit reverts. |
pending | boolean | false | The page's word that a command is on its way (e.g. data-attr:pending="$_saving"): :state(pending) and aria-busy while present. It adds to confirm's pending, never clears it. |
Events
| Name | Description |
|---|---|
change | After the user checks or clears the box. |
sb-change | Same moment. detail: { name, value, checked } (value is the checked state): ready for a command. |