Playground
One choice out of a handful, the form primitive a <select> is too small for. Write the choices as sb-radio children, or let the server fill options. The group keeps a single value, emits sb-change when the user commits a choice, and follows the command contract, so it can drive a command as it is.
sb-radio is not a component of its own. Like <option> inside a native <select>, it is markup the group reads: value, label, description and disabled. The value falls back to the label, then to the text. A choice needs a non-empty value: "" is the group's "nothing chosen", so <sb-radio value="">Any</sb-radio> is left out (give "Any" a value of its own, e.g. value="any"). The group renders every item in its own shadow root, so the repeated rows contain no custom elements, the roving focus never has to cross a shadow boundary, and a Datastar morph over the group can't trip over a nested upgrade.
Examples
Basic
<sb-radio-group label="Drive mode" value="warp">
<sb-radio value="impulse">Impulse</sb-radio>
<sb-radio value="warp">Warp</sb-radio>
<sb-radio value="tow" disabled>Tow (needs a tug)</sb-radio>
</sb-radio-group>
Descriptions and a row
description adds a second line, and orientation="horizontal" lays the choices out in a row that wraps.
<div style="display: grid; gap: 24px">
<sb-radio-group label="Shield profile" value="balanced">
<sb-radio value="balanced" description="Even coverage, no surprises">Balanced</sb-radio>
<sb-radio value="forward" description="Everything to the bow">Forward</sb-radio>
<sb-radio value="off" description="For when the sensors need silence">Off</sb-radio>
</sb-radio-group>
<sb-radio-group label="Rations" orientation="horizontal" value="double">
<sb-radio value="single">Single</sb-radio>
<sb-radio value="double">Double</sb-radio>
<sb-radio value="feast">Feast</sb-radio>
</sb-radio-group>
</div>
Segmented
variant="segmented" lays the choices out as a row of pills, sized like sb-button (size: sm, md, lg), with the chosen one filled. It is the same radio group: one value, the same keys, form data and command contract. When the row runs out of room, the pills wrap onto the next line, so every choice stays visible; descriptions are not shown.
<div lang="de" style="display: grid; gap: 24px">
<sb-radio-group label="E-Mail bei neuen Beiträgen" variant="segmented" value="daily">
<sb-radio value="now">Sofort</sb-radio>
<sb-radio value="daily">Täglich</sb-radio>
<sb-radio value="never">Nie</sb-radio>
</sb-radio-group>
<sb-radio-group label="Anonym teilnehmen?" variant="segmented" size="sm" value="no">
<sb-radio value="yes">Ja</sb-radio>
<sb-radio value="no">Nein</sb-radio>
</sb-radio-group>
</div>
Choices from the server
options takes the same shape as sb-select: strings, or {value, label, description?, disabled?}. It is server data, so it only flows in. Children win over it when both are there.
<sb-radio-group label="Dock" value="b"
options='[{"value":"a","label":"Bay A"},{"value":"b","label":"Bay B","description":"Closest to the lift"},{"value":"c","label":"Bay C","disabled":true}]'></sb-radio-group>
Two-way binding
The live value is the value property, so data-bind works with the __prop and __event modifiers. Declare the signal first.
Engaged:
<div data-signals:_drive="'impulse'">
<sb-radio-group label="Drive mode" data-bind:_drive__prop.value__event.change>
<sb-radio value="impulse">Impulse</sb-radio>
<sb-radio value="warp">Warp</sb-radio>
</sb-radio-group>
<p>Engaged: <strong data-text="$_drive"></strong></p>
</div>
With commands
Give it a name, and it emits sb-change with { name, value } when the user commits a choice: ready to post as a command. With confirm, it sets :state(pending) until the server's re-rendered value attribute matches, and revert() goes back to the server's value when a command never reaches the server (an error status, or retries-failed).
<sb-radio-group name="drive" confirm value="impulse" label="Drive mode"
data-on:sb-change="@post('/cmd/drive', {payload: {tabid: $tabid, ...evt.detail}})"
data-on:datastar-fetch="evt.detail.el === el && ['error', 'retries-failed'].includes(evt.detail.type) && el.revert()">
<sb-radio value="impulse">Impulse</sb-radio>
<sb-radio value="warp">Warp</sb-radio>
</sb-radio-group>
Style the wait from the page:
sb-radio-group:state(pending) { opacity: 0.7; }
The value attribute is the server's value, and it wins whenever it changes: a morph with a new value replaces the local choice, re-sent identical markup leaves the user's choice alone, and a removed attribute is ignored (to clear, the server sends value="", which also works on a group that had no value before). Nothing else is server state: the live value before the echo, the roving focus, the hover and the pending state all 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 value win even when it is unchanged, so a refused choice 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 value applies once. 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".
sb-radio children are not components
sb-radio is never defined as a custom element: the group reads its attributes and text and renders the choices itself, so every sb-radio stays :not(:defined) for good. A generic check that every custom element on a page got defined (a test, or a script that waits for them) has to leave them out:
document.querySelectorAll(':not(:defined):not(sb-radio)')
Forms
Inside a <form>, sb-radio-group submits the checked choice under its name (name=value), new FormData(form) and Datastar's contentType: 'form' include it, and a form reset brings back the server's value without change events. As with radios, nothing is submitted when no choice is checked or the checked one is disabled, and nothing without a name or while the group is disabled. 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).
Text and language
The only text the group shows is its own label (no default). The choices' words are yours: the sb-radio children's text, label and description, or the options from the server. Without a label, the host's aria-label or aria-labelledby names the group. It formats no numbers or dates.
Styling
Parts: base, label, items, item (each choice, a pill when segmented), checked (the chosen item, as well: ::part(item checked)), dot and description. Colours come from the control and brand tokens (a checked choice is a --sb-brand dot in a --sb-brand-light ring, on a --sb-brand-subtle tint; a segmented pill is filled with --sb-control-border, and the chosen one --sb-brand with --sb-text-on-brand text; under the pointer a pill takes --sb-segment-hover, by default its fill moved 12% toward --sb-control-text, so the text stays readable in a theme whose --sb-control-border-hover is close to its text colour), the corners from --sb-notch, so [data-sb-style="smooth"] rounds them instead: pixel corners on the pills, fully round ends at --sb-notch: 0, where nothing is clipped, so a page's box-shadow on a part shows. A disabled group has :state(disabled), from the decoded prop, never from :host([disabled]).
<sb-radio-group label="Hull paint" value="rust" style="--sb-brand: #F5C451; --sb-brand-light: #FFE08A; --sb-brand-subtle: rgb(245 196 81 / 0.16)">
<sb-radio value="rust">Rust</sb-radio>
<sb-radio value="chrome">Chrome</sb-radio>
</sb-radio-group>
Accessibility
The element itself is the radiogroup, with aria-orientation (and aria-disabled when disabled), set through ElementInternals so a morph can't strip them. The label names it. Without one, give the element an aria-label or aria-labelledby: they name the group too, and win over the label. Each item is a role="radio" with aria-checked, and its description is part of its accessible name.
Only one item is in the tab order: the checked one, or the first enabled one when nothing is checked. Disabled items don't take the focus, not even from a click. Arrow keys move and select, as native radios do, wrapping around and skipping disabled items. Left and Right follow the reading direction (in right-to-left text, Left moves on), and arrows with Alt, Ctrl or Meta are left to the browser (Alt+Left goes back). Home and End jump to the first and last enabled choice; Space (and Enter) selects the focused one. The focus survives a re-render: the items are driven by signals, and when the focused choice is dropped or disabled, its neighbour takes the focus. Once the focus has left the group, a click on the page's text included, the group doesn't take it back.
The segmented variant is the same group, laid out in a row: aria-orientation is horizontal there, whatever orientation says.
In forced colours (Windows High Contrast), the checked dot is filled with the system's Highlight colour; segmented pills get a ButtonText border, and the chosen one is filled with Highlight.
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-radio-group value="warp" orientation="horizontal">
<sb-radio value="impulse">Impulse</sb-radio>
<sb-radio value="warp">Warp</sb-radio>
</sb-radio-group>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/radio-group@72e1a9173cab/radio-group.bundle.min.js" integrity="sha384-73Z7V9VgI8FBbwvNMchdUlUwX9UvqYIgjV60a7IELrVLheK28vSraIskB8kd3/vL"></script>
<sb-radio-group value="warp" orientation="horizontal">
<sb-radio value="impulse">Impulse</sb-radio>
<sb-radio value="warp">Warp</sb-radio>
</sb-radio-group>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/radio-group@72e1a9173cab/radio-group.min.js": "sha384-uqty9C7ZmicVcEaeoeHdWJXbRrDsxQYx5b3v5iIYw7E1dxq0RvB/IeRlZ1BcnhZk"
}
}
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/radio-group@72e1a9173cab/radio-group.min.js" integrity="sha384-uqty9C7ZmicVcEaeoeHdWJXbRrDsxQYx5b3v5iIYw7E1dxq0RvB/IeRlZ1BcnhZk"></script>
<sb-radio-group value="warp" orientation="horizontal">
<sb-radio value="impulse">Impulse</sb-radio>
<sb-radio value="warp">Warp</sb-radio>
</sb-radio-group>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/radio-group@72e1a9173cab/radio-group.bundle.min.js": "sha384-73Z7V9VgI8FBbwvNMchdUlUwX9UvqYIgjV60a7IELrVLheK28vSraIskB8kd3/vL"
}
}
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/@81f24b268adb/autoloader.js" integrity="sha384-bWIhsIq9SpNUiIZyG/lv190MgHA05m8BVYA3LyIoE/pgOF3NUt0437e++4Ht1NcS"></script>
<sb-radio-group value="warp" orientation="horizontal">
<sb-radio value="impulse">Impulse</sb-radio>
<sb-radio value="warp">Warp</sb-radio>
</sb-radio-group>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-radio-group>radio-group.bundle.min.jsone file 3.2 kB brotli
<script type="importmap">
{ "imports": { "datastar": "/js/datastar-rocket.js" } }
</script>
<script type="module" src="/js/radio-group/radio-group.bundle.min.js"></script>
<sb-radio-group value="warp" orientation="horizontal">
<sb-radio value="impulse">Impulse</sb-radio>
<sb-radio value="warp">Warp</sb-radio>
</sb-radio-group>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/radio-group/radio-group.min.js"></script>
<sb-radio-group value="warp" orientation="horizontal">
<sb-radio value="impulse">Impulse</sb-radio>
<sb-radio value="warp">Warp</sb-radio>
</sb-radio-group>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.TagRadioGroup}})
// 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.RadioGroup(sb.RadioGroupProps{
Value: sb.Str("warp"),
Orientation: sb.RadioGroupOrientationHorizontal,
}) {
<sb-radio value="impulse">Impulse</sb-radio>
<sb-radio value="warp">Warp</sb-radio>
}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 |
|---|---|---|---|
radio-group.bundle.min.js | 8.9 kB | 3.6 kB | 3.2 kB |
As module files: one request, 3.2 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 |
|---|---|---|---|---|
radio-group.js | 20.1 kB | 7.4 kB | 6.4 kB | 3.2 kB |
API reference
Props
| Attribute | Type | Default | Description |
|---|---|---|---|
value | string | "" | The selected value. A new value from the server replaces it; the live value is the value property. |
options | json | [] | Choices from the server: ["A", "B"] or [{value, label, description?, disabled?}]. <sb-radio> children win over it. |
label | string | "" | Visible label, and the accessible name of the group. |
orientation | "vertical" | "horizontal" | "vertical" | Stack the choices or lay them out in a row. |
variant | "default" | "segmented" | "default" | default: radios, stacked or in a row (see orientation). segmented: a row of pills, sized like sb-button, that wraps when it runs out of room (descriptions are not shown). |
size | "sm" | "md" | "lg" | "md" | Segmented: the pills' height and padding, as sb-button's sizes. |
disabled | boolean | false | Disable the whole group. |
confirm | boolean | false | Server-confirmed value: :state(pending) while the local value differs from the server's value 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 value attribute win 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. |
name | string | "" | Name reported in sb-change (e.g. the field of a command), and the field it submits in a form. |
Slots
| Name | Description |
|---|---|
| <sb-radio value="…" [description] [disabled]>Label</sb-radio> items: markup the group reads as its choices, like <option> in a native <select>. Nothing is slotted; the group renders the items itself. |
Events
| Name | Description |
|---|---|
change | When the user picks a choice. |
sb-change | Same moment. detail: { name, value }: ready for a command. |