Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Exclusive choice

Use radios when the reader must pick exactly one of a few options, with every choice visible at once.

One value, all options visible
Every radio in the group carries the same name; the checked one matches the current value.
Show code
<div class="wui-control-group">
    <app-radio label="No experience" name="exp" value="none"></app-radio>
    <app-radio label="1 year" name="exp" value="1" checked="true"></app-radio>
    <app-radio label="2+ years" name="exp" value="2"></app-radio>
</div>

Validation

Helper text gives guidance on any radio in the group, and an error replaces it when the choice is missing.

Helper text and error
Rounded to the nearest year.
Choose an experience level.
Show code
<app-radio label="1 year" name="exp-hint" value="1" helper-text="Rounded to the nearest year."></app-radio>
<app-radio label="1 year" name="exp-error" value="1" error="Choose an experience level."></app-radio>

Control only

Control only draws just the radio, for a dense form that draws its own labels and messages.

Control only
Show code
<label class="d-flex gap-2 align-items-center"><app-radio control-only="true" name="co-answer" value="yes" /> Yes</label>
<label class="d-flex gap-2 align-items-center"><app-radio control-only="true" name="co-answer" value="no" /> No</label>

Every option

Every value of every prop, one cell each.

label

label="Option"
label omitted: bare control, no accessible name
label long: wraps inside the control group

id, name and value

id="mtx-id"
name="mtx-name"
value="b"

state

unchecked (default)
checked
disabled
disabled checked
read-only
loading

defaultChecked

defaultChecked: React only, Razor uses checked

validation

helper-text="Helper text"
Helper text
error="Required"
Required
helper-text + error (error wins)
Helper text
Required

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-label

className

class: extra class on the wrapper

onChange and ref

onChange: React only, fires when chosen
ref: React only, Razor binds with asp-for

asp-for

asp-for: binds to a Razor model property

Guidance

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

Do

2 to 5 exclusive options, all on screen. The user compares every choice without opening anything.

Avoid

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

Do

Radios enforce a single answer. Exactly one can ever be selected.

Avoid

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.

unset sm md lg
React, generated from the controls
<AppRadio label="Option A" name="playground" value="a" />
Razor, the same props
<app-radio label="Option A" name="playground" value="a" />

14 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
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

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

Two to five options, all visible

Do

2 to 5 exclusive options, all on screen. The user compares every choice without opening anything.

Avoid

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

Do

Radios enforce a single answer. Exactly one can ever be selected.

Avoid

Checkboxes let the user tick several, the wrong control for a single exclusive choice.