On this page
@addTagHelper *, Webority.Ui.RazorExclusive choice
Use radios when the reader must pick exactly one of a few options, with every choice visible at once.
Validation
Helper text gives guidance on any radio in the group, and an error replaces it when the choice is missing.
Control only
Control only draws just the radio, for a dense form that draws its own labels and messages.
Every option
Every value of every prop, one cell each.
label
label="Option"label omitted: bare control, no accessible namelabel long: wraps inside the control groupid, name and value
id="mtx-id"name="mtx-name"value="b"state
unchecked (default)checkeddisableddisabled checkedread-onlyloadingdefaultChecked
defaultChecked: React only, Razor uses checkedvalidation
helper-text="Helper text"error="Required"helper-text + error (error wins)help
help="Help text"help-label="Explain this option" (with help)size
size="sm"size="md" (default)size="lg"controlOnly
control-only: draws the control alone, named by aria-labelclassName
class: extra class on the wrapperonChange and ref
onChange: React only, fires when chosenref: React only, Razor binds with asp-forasp-for
asp-for: binds to a Razor model propertyGuidance
What to do, and what to avoid.
Use it when
- The user must pick exactly one of 2 to 5 mutually exclusive options.
- The options are short labels worth comparing at a glance, all visible.
- A single choice is mandatory before the form can be submitted.
Reach for something else when
- There are more than about five options. → AppSelect
- Each option needs a description or icon. → AppChoiceCard
- The choices are independent on/off settings. → AppCheckbox
- The user can pick several values. → AppSelect mode="multiple"
Two to five options, all visible
2 to 5 exclusive options, all on screen. The user compares every choice without opening anything.
Past about five options a radio list sprawls and is hard to scan. A dropdown holds it in one line.
Radios for one answer, not checkboxes
Radios enforce a single answer. Exactly one can ever be selected.
Checkboxes let the user tick several, the wrong control for a single exclusive choice.
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
14 props. The 5 most used come first.
Used on most screens 5 props
| Prop | Type | Default | Description |
|---|---|---|---|
| labeldefault - | string | - | The clickable label beside the radio. |
| namedefault - | string | - | The form field name. Radios that share a name form one group. |
| valuedefault - | string | - | The value this radio posts when it is the chosen one. |
| checkeddefault false | bool | false | Controlled chosen state; pair with onChange. |
| disableddefault false | bool | false | Locks the radio and dims it. |
Less common 9 props
| Prop | Type | Default | Description |
|---|---|---|---|
| iddefault - | string | - | The input's id. The label is bound to the input through it, and it is generated when left out. |
| asp-fordefault - | ModelExpression | - | Razor-only. Binds name, id, checked state and validation message from a Razor Pages model property. |
| errordefault - | string | - | Error message, rendered below the control. Replaces the helper text. |
| helper-textdefault - | string | - | Helper text below the control. Hidden while an error is shown. |
| read-onlydefault false | bool | false | Shows the value but blocks editing. The value still posts. |
| loadingdefault false | bool | false | Shows a busy state and blocks input while data loads. |
| helpdefault - | string | - | Content for the info-tip after the label. Shown only when a label is set. |
| help-labeldefault More information | string | More information | aria-label for the info-tip button. |
| sizedefault md | sm | md | lg | md | The control size: sm, md or lg. |
Screen reader
2 notes- Each radio's label is bound to its input through id and htmlFor, so a click on the text selects it and a screen reader announces the name.
- Radios that share a name form one native group, so arrow keys move between them. The component does not change that.
Do and avoid
2 pairsTwo to five options, all visible
2 to 5 exclusive options, all on screen. The user compares every choice without opening anything.
Past about five options a radio list sprawls and is hard to scan. A dropdown holds it in one line.
Radios for one answer, not checkboxes
Radios enforce a single answer. Exactly one can ever be selected.
Checkboxes let the user tick several, the wrong control for a single exclusive choice.