Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Basic

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
Show code
<app-radio-group label="Delivery speed" name="delivery" value="standard">
    <app-option value="standard">Standard (3 to 5 days)</app-option>
    <app-option value="express">Express (1 to 2 days)</app-option>
    <app-option value="same-day">Same day (Mumbai, Delhi, Bengaluru)</app-option>
</app-radio-group>

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
Show code
<app-radio-group inline="true" label="Billing cycle" name="billing" value="monthly">…</app-radio-group>

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.
Show code
<app-radio-group variant="AppRadioGroupVariant.Card" label="Typical figures" name="downtime" value="1">
    <app-option value="0.1" description="A stoppage halts the whole line.">0.1, critical equipment</app-option>
    <app-option value="1" description="Work carries on while it is repaired.">1, not critical</app-option>
    <app-option value="own">The owner's own figure</app-option>
</app-radio-group>
Cards in a row
With inline, the cards share the row and wrap onto a column on a phone.
Billing cycle
Show code
<app-radio-group variant="AppRadioGroupVariant.Card" inline="true" label="Billing cycle" name="billing" value="monthly">…</app-radio-group>
Card states
Delivery speed
Choose a delivery speed.
Delivery speed
Show code
<app-radio-group variant="AppRadioGroupVariant.Card" error="Choose a delivery speed." required="true" …>…</app-radio-group>
<app-option value="same-day" disabled="true">…</app-option>

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
Yearly billing saves two months.
Delivery speed
Choose a delivery speed.
Delivery speed (one option off)
Billing cycle (disabled)
Show code
<app-radio-group helper-text="You can change this later." …>…</app-radio-group>
<app-radio-group error="Choose a delivery speed." required="true" …>…</app-radio-group>
<app-option value="same-day" disabled="true">Same day</app-option>
<app-radio-group disabled="true" …>…</app-radio-group>

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
Choose a billing cycle.

helper-text

helper-text="Yearly billing saves two months."
Billing cycle
Yearly billing saves two months.

help

help="Monthly is the most flexible choice." (opens an info tip beside the label)
Billing cycle

help-label

help-label (names the info tip button, no visible effect)
Billing cycle

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.

monthly quarterly yearly
default card
(default) sm md lg
Billing cycle
React, generated from the controls
<AppRadioGroup
  name="billing"
  label="Billing cycle"
  options={[
    { value: 'monthly', label: 'Monthly' },
    { value: 'quarterly', label: 'Quarterly' },
    { value: 'yearly', label: 'Yearly' },
  ]}
  value={value}
  onChange={setValue}
/>
Razor, the same props
<app-radio-group name="billing" label="Billing cycle" value="monthly">
    <app-option value="monthly">Monthly</app-option>
    <app-option value="quarterly">Quarterly</app-option>
    <app-option value="yearly">Yearly</app-option>
</app-radio-group>

25 props. The 4 most used come first.

Used on most screens 4 props

PropTypeDefaultDescription
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

PropTypeDefaultDescription
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.