HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
RadioView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorOne choice in a radio group.StableSince 0.1.0FormsUsageimport'@fusion.dev/helix/radio'import'@fusion.dev/helix-headless/radio'Preview
API ReferenceRoothelix-radioOne choice in a radio group.
PropTypeDescriptiondefaultSelectedbooleanWhether the markup declares the radio chosen. A form reset returns to it.disabledbooleanDefaultfalseWhether the item is disabled and cannot be chosen.focusablebooleanWhether the radio holds the group's tab stop. Unset, the chosen radio
holds it.hideControlbooleanDefaultfalseHides the circle, so the card is the whole control.selectedbooleanDefaultfalseWhether the item is selected.separation"filled"|"outlined"|"plain"How the choice's own surface is set apart from its surroundings.valuestringDefault""The item's value, which identifies it in its set and is what a form
submits.variant"chip"Draws the choice as a small chip, for a row of short choices.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The radio's label.iconAn icon shown beside the label. With variant="chip", the icon replaces the visible label, and the label becomes the name read by screen readers. The icon has its own slot so the chip can hide the label and show the icon.indicatorAn icon drawn inside the circle in place of the dot, such as a check mark.
EventTypeDescriptionhelix-selectHelixSelectEventFired when the radio is chosen. Cancelable: call preventDefault() to keep the current choice.
MethodTypeDescriptionclick() => voidChooses the radio, as click() does a native radio: passed to the control
inside, so the one click a listener hears is the control's, after it has
moved. See HostClickController.focusItem() => voidMoves focus to the item's control, for the set's arrow keys.select() => booleanSelects the item and fires helix-select. Returns false if the item is
disabled or a listener cancels the event.
PartDescriptionboxThe circle. Draw the dot inside it with ::part(box)::after in your stylesheet, or slot an icon into indicator. This tier ships no CSS, so it renders no separate element for the dot, which would add an empty child to your layout.itemThe button, which covers the whole row.labelThe label beside the circle.
CSS PropertyDescription--radio-background-colorThe fill of an unselected circle.--radio-border-colorThe border color of the circle, in every state.--radio-card-background-colorThe fill behind a card-shaped choice.--radio-card-border-colorThe border color of a card-shaped choice.--radio-card-paddingThe padding inside a card-shaped choice.--radio-chip-sizeThe diameter of a chip.--radio-indicator-sizeThe width and height of an icon slotted into indicator. Three quarters of the circle by default.--radio-mark-colorThe color of the dot, or of an icon slotted into indicator.--radio-sizeThe diameter of the circle.
Custom stateDescriptionhas-indicatorAn icon is slotted into indicator.selectedThe radio is chosen.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Grouphelix-radio-groupA set of radios where exactly one can be chosen.
PropTypeDescriptiondefaultValuestringDefault""The value the control starts with. A form reset returns it to this value,
and to the value attribute where this one is not written, as a native
control resets to the value it declares.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.feedbackstringDefault""The validation message shown under the control. It replaces the
browser's message.focusablebooleanDefaulttrueWhether the group holds a tab stop of its own.hintstringDefault""Help text shown under the control. A validation message replaces it.labelstringDefault""The field's label, which is also its accessible name. Content in the
label slot replaces it.namestringDefault""The name the control's value is submitted under.orientation"horizontal"|"vertical"The direction the choices run. vertical puts one choice on each line.readOnlybooleanDefaultfalseWhether a reader can see and focus the answer and cannot change it. A
read-only group still submits its value.requiredbooleanDefaultfalseWhether the field needs a value before the form can submit.valuestringThe control's current value, which its form submits.valueMissingMessagestringDefault"Choose one to continue."The message shown when the field is required and empty.
ReadTypeDescriptionformHTMLFormElement|nullThe form the control belongs to, or null.itemsHelixHeadlessRadio[]The radios, in light-DOM order. Client only: the server has no tree.labelsNodeListThe labels associated with the control.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
SlotDescription(default)The radios.feedbackThe error message, for content richer than a string. It shows while there is a message.hintThe help text under the group, for content richer than a string.labelThe group's label, for a question that needs more than a string.
EventTypeDescriptionchangeEventFired after the value changes.helix-before-changeHelixBeforeChangeEventFired when the choice changes. Cancelable: call preventDefault() to keep the current choice.helix-selectHelixSelectEventFired when a radio is chosen. The radio sends it, and you listen for it on the group. Cancelable: call preventDefault() to keep the current choice.inputEventFired after the value changes.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.focus(options: FocusOptions) => voidMoves focus to the control, as focusing a native control does.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.requestValue(next: string) => booleanRequests a new value, and returns whether the change was applied.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.
PartDescriptionfeedbackThe error message under the group.hintThe help text under the group.itemsThe container of the choices, laid out by orientation.labelThe label above the group.
CSS PropertyDescription--radio-group-gapThe space between the choices.
Custom stateDescriptioninvalidThe group has an error to show, from the browser's validation or from your feedback.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-radioOne choice in a radio group.
PropTypeDescriptiondefaultSelectedbooleanWhether the markup declares the radio chosen. A form reset returns to it.disabledbooleanDefaultfalseWhether the item is disabled and cannot be chosen.focusablebooleanWhether the radio holds the group's tab stop. Unset, the chosen radio
holds it.selectedbooleanDefaultfalseWhether the item is selected.valuestringDefault""The item's value, which identifies it in its set and is what a form
submits.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The radio's label.iconAn icon shown beside the label. With variant="chip", the icon replaces the visible label, and the label becomes the name read by screen readers. The icon has its own slot so the chip can hide the label and show the icon.indicatorAn icon drawn inside the circle in place of the dot, such as a check mark.
EventTypeDescriptionhelix-selectHelixSelectEventFired when the radio is chosen. Cancelable: call preventDefault() to keep the current choice.
MethodTypeDescriptionclick() => voidChooses the radio, as click() does a native radio: passed to the control
inside, so the one click a listener hears is the control's, after it has
moved. See HostClickController.focusItem() => voidMoves focus to the item's control, for the set's arrow keys.select() => booleanSelects the item and fires helix-select. Returns false if the item is
disabled or a listener cancels the event.
PartDescriptionboxThe circle. Draw the dot inside it with ::part(box)::after in your stylesheet, or slot an icon into indicator. This tier ships no CSS, so it renders no separate element for the dot, which would add an empty child to your layout.itemThe button, which covers the whole row.labelThe label beside the circle.
Custom stateDescriptionhas-indicatorAn icon is slotted into indicator.selectedThe radio is chosen.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Grouphelix-headless-radio-groupA set of radios where exactly one can be chosen.
PropTypeDescriptiondefaultValuestringDefault""The value the control starts with. A form reset returns it to this value,
and to the value attribute where this one is not written, as a native
control resets to the value it declares.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.feedbackstringDefault""The validation message shown under the control. It replaces the
browser's message.focusablebooleanDefaulttrueWhether the group holds a tab stop of its own.hintstringDefault""Help text shown under the control. A validation message replaces it.labelstringDefault""The field's label, which is also its accessible name. Content in the
label slot replaces it.namestringDefault""The name the control's value is submitted under.orientation"horizontal"|"vertical"The direction the choices run. vertical puts one choice on each line.readOnlybooleanDefaultfalseWhether a reader can see and focus the answer and cannot change it. A
read-only group still submits its value.requiredbooleanDefaultfalseWhether the field needs a value before the form can submit.valuestringThe control's current value, which its form submits.valueMissingMessagestringDefault"Choose one to continue."The message reported when the field is required and no option is chosen.
Absent, or empty, is this sentence, or the words registered for the page's
locale.
ReadTypeDescriptionformHTMLFormElement|nullThe form the control belongs to, or null.itemsHelixHeadlessRadio[]The radios, in light-DOM order. Client only: the server has no tree.labelsNodeListThe labels associated with the control.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
SlotDescription(default)The radios.feedbackThe error message, for content richer than a string. It shows while there is a message.hintThe help text under the group, for content richer than a string.labelThe group's label, for a question that needs more than a string.
EventTypeDescriptionchangeEventFired after the value changes.helix-before-changeHelixBeforeChangeEventFired when the choice changes. Cancelable: call preventDefault() to keep the current choice.helix-selectHelixSelectEventFired when a radio is chosen. The radio sends it, and you listen for it on the group. Cancelable: call preventDefault() to keep the current choice.inputEventFired after the value changes.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.focus(options: FocusOptions) => voidMoves focus to the control, as focusing a native control does.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.requestValue(next: string) => booleanRequests a new value, and returns whether the change was applied.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.
PartDescriptionfeedbackThe error message under the group.hintThe help text under the group.itemsThe container of the choices, laid out by orientation.labelThe label above the group.
Custom stateDescriptioninvalidThe group has an error to show, from the browser's validation or from your feedback.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionCardsRadios drawn as cards, for choices that need a description.ChipsA satisfaction scale of five chips, each with an icon, a value, and a name.DisabledA disabled group, and a group disabled by the fieldset around it.EventsThe group fires events for the set, and the radio that is pressed fires its own.Hide ControlCards with the circle hidden, so the whole card is the control.HorizontalThe options in a row, for a short scale.InvalidThe group showing an error because nothing was chosen.PreviewOne choice from several, with a hint under the label.PreviewOne choice from several, with a hint under the label.RequiredA group that needs a choice before the form submits.