Radio Button Group
import "@taprootio/espalier/radio-button/group";
<esp-radio-button-group>
Groups multiple esp-radio-button components and ensures only one can be selected at a time. Works with esp-form-item for label and error message integration.
Inside an esp-form-item, the group's radiogroup element takes the form
item's label as its accessible name and its hint as its description.
While the form item shows an error, that element is aria-invalid="true"
and the error joins its description after the hint. Each option keeps its
own label and is not described separately.
Slots
<esp-radio-button-group> has a slot:
Default
Place esp-radio-button elements in the default slot.
Attributes
<esp-radio-button-group> has the following attributes:
name
name has a default value of "".
The name used when the group participates in a <form>.
required
required has a default value of false.
When true, one radio button must be selected before the form can be submitted.
required-message
required-message has a default value of "".
A custom message to display when the group is required but no
radio button is selected. Defaults to
"Please select an option." when not set.
disabled
disabled has a default value of false.
Disables all child radio buttons in the group.
surface-layer
surface-layer has a default value of undefined.
Declares the painted surface depth. Fields use the next local layer, capped at layer 4.
intent
intent has a default value of undefined.
The element's intent — its meaning: neutral
(no pin), or success, warning, danger, info — each pinned
to its fixed status family (blue for info), retunable per theme
via intents. On token-emitting controls a non-neutral intent pins the
filled-action pair to that family, derived over the governing
zone's theme; class-styled chrome (badges, callouts, status pills)
opts out of inline emission and renders its treatment from CSS
classes instead. An intent never repaints the surrounding zone,
which is what contexts are for. Removing the attribute restores
the element's own default intent.
context
context has a default value of undefined.
A theme-defined color zone. The selected context rebinds designer-facing roles and emits a complete, contrast-enforced semantic token table on this host for descendants to inherit.
Methods
<esp-radio-button-group> has the following methods:
focus
Focus the checked radio button, or the first non-disabled radio button if none is checked.
validate
Re-run constraint validation and dispatch esp-validity-changed.
checkValidity
Check whether the current state is valid (delegates to ElementInternals).
traverseToClosest
Traverse up the DOM tree to find the closest element that matches the selector. This method is aware of shadow DOM boundaries and will traverse through them to find the element.
Events
<esp-radio-button-group> emits the following events:
esp-value-changed
esp-value-changed is of type CustomEvent<string>.
Fired when the selected radio button changes. The detail is the value of the newly selected radio button.
esp-validity-changed
esp-validity-changed is of type CustomEvent<{ valid: boolean; message: string }>.
Fired whenever constraint validation runs.
CSS Properties
<esp-radio-button-group> has the following CSS properties:
--esp-field-background
Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at var(--esp-color-layer-4), or var(--esp-color-layer-2) without a declared surface. An explicit override wins.
--esp-field-border-color
Border color of the shared field shell. Defaults to var(--esp-color-border).
--esp-field-border-width
Border width of the shared field shell. Defaults to 1px.
--esp-field-text-color
Text color used inside the shared field shell. Defaults to var(--esp-color-text).
--esp-field-hover-bg
Hover background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-bg
Focus background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-shadow
Shadow color used for shared field focus treatment. Defaults to var(--esp-color-shadow).