On this page
@addTagHelper *, Webority.Ui.RazorBasic
Give the group a label, its options and the selected value; the options stack in a column by default.
A stacked group
onChange gets the new value, not the event. Use asp-for="Plan.BillingCycle" instead of name, value and label. The tag helper reads the name, the selected value, the display name, the required mark and the validation message from the property.
Delivery speed
Inline
Lay the options out in a row for short labels such as billing periods; they wrap when space runs out.
A row of options
Best for short labels such as billing periods.
Billing cycle
Card
Draw each option as a bordered card for a few weighty choices, each with a line of explanation.
Options as cards
Use it for a few weighty choices, where a bigger target and a line of explanation help.
Typical figures
A stoppage halts the whole line.
Work carries on while it is repaired.
Cards in a row
With inline, the cards share the row and wrap onto a column on a phone.
Billing cycle
Card states
Delivery speed
Delivery speed
States
Helper text explains the choice, an error replaces it, and required or disabled sets the state of the group.
Helper text, error, required and disabled
When both are set, only the error shows. The group is marked invalid and the error text is linked to it for screen readers.
Billing cycle
Delivery speed
Delivery speed (one option off)
Billing cycle (disabled)
Every option
Every value of every prop, one cell each.
label
label
Billing cycle
options
app-option children (React: options)
Delivery speed
app-option description
Typical figures
A stoppage halts the whole line.
Work carries on while it is repaired.
name
name (posted field name, no visible effect)
Billing cycle
value
value (selected)
Billing cycle
defaultValue
defaultValue (React only, Razor uses value)
Billing cycle
onChange
onChange (Razor posts the value with the form)
Billing cycle
variant
variant="default" (default)
Billing cycle
variant="card"
Billing cycle
inline
inline="false" (default)
Billing cycle
inline="true"
Billing cycle
required
required="true"
Billing cycle
disabled: whole group vs. one option
disabled="true"
Billing cycle
app-option disabled="true"
Delivery speed
read-only
read-only="true"
Billing cycle
loading
loading="true"
Billing cycle
error
error="Choose a billing cycle."
Billing cycle
helper-text
helper-text="Yearly billing saves two months."
Billing cycle
help
help="Monthly is the most flexible choice." (opens an info tip beside the label)
Billing cycle
More information
Monthly is the most flexible choice.
help-label
help-label (names the info tip button, no visible effect)
Billing cycle
About billing cycles
Monthly is the most flexible choice.
id
id (no visible effect)
Billing cycle
size
size="sm"
Billing cycle
size="md" (default)
Billing cycle
size="lg"
Billing cycle
input-class
input-class (a class on the group, no visible effect here)
Billing cycle
class
class (a class on the .field wrapper, no visible effect here)
Billing cycle
style
style (lands on the group, as input-class does)
Billing cycle
optional
optional="true"
Delivery speed (optional)
optional-label
optional-label="(if you wish)"
Delivery speed (if you wish)
asp-for (Razor only)
asp-for (sets name, value, label and the validation message)
Billing cycle
Guidance
What to do, and what to avoid.
Use it when
- Two to five exclusive options, and the reader should see all of them before choosing.
- The choice is a field in a form that sits in the same grid as the other fields.
- You need helper text, an error or a required mark on the group as a whole.
Reach for something else when
- There are six or more options. → AppSelect
- It is a control strip that changes a view at once. → AppSegmented
- Each option needs an icon, an image or a description. → AppChoiceCard
- You need one standalone radio, not a group. → AppRadio
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
25 props. The 4 most used come first.
Used on most screens 4 props
| Prop | Type | Default | Description |
|---|---|---|---|
| labeldefault - | string | - | The visible group label. It is also the group's accessible name. |
| namedefault generated | string | generated | Shared name of the radios. Defaults to a generated one. |
| valuedefault - | string | - | Selected value (controlled). |
| defaultValuedefault - | string | - | Use value in Razor. |
Less common 21 props
| Prop | Type | Default | Description |
|---|---|---|---|
| asp-fordefault - | ModelExpression | - | The model property to bind to. Supplies the name, the selected value, the label, the required mark and the validation message. |
| variantdefault default | default | card | default | Draws each option as a bordered card the whole of which selects it; the chosen card takes the primary border and a tinted fill. |
| inlinedefault false | bool | false | Options in a row (wrapping) instead of a column. |
| requireddefault false | bool | false | Marks the group and each option as required: the label shows the required mark, the group takes aria-required and each input the required attribute. |
| optionaldefault false | bool | false | Ends the label with (optional) when the field is not required. Required wins when both are set. |
| disableddefault false | bool | false | Disables every option. |
| 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. |
| sizedefault md | sm | md | lg | md | Steps the radios and their labels. |
| errordefault - | string | - | Error message below the group. Replaces the helper text. |
| helper-textdefault - | string | - | Helper text below the group. |
| optional-labeldefault (optional) | string | (optional) | Replaces the built-in English text, for other languages. |
| helpdefault - | string | - | Content for the info-tip beside the label. |
| help-labeldefault More information | string | More information | aria-label for the info-tip button. |
| iddefault generated | string | generated | The group's id; generated when left out. Option ids and the label and message ids derive from it. |
| input-classdefault - | string | - | Extra classes on the group (the control). A style attribute lands here too. |
| classdefault - | string | - | A plain class lands on the .field wrapper. |
| app-option valuedefault - | string | - | On an app-option child: the value that posts when this radio is chosen. |
| app-option descriptiondefault - | string | - | On an app-option child: a muted line under the label, read as the radio's description. |
| app-option disableddefault false | bool | false | On an app-option child: keeps the option visible but unpickable. The element's content is its label. |
| onChangedefault - | (value) => void | - | Razor posts the chosen value with the form. |
Screen reader
3 notes- The group is a radiogroup named by its label, so a screen reader announces the label as the group's name.
- Each option's label is bound to its radio through htmlFor, so a click on the text selects it.
- Helper text or an error is linked to the group through aria-describedby.