Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Label and checked

A checkbox is its label plus its checked state, and the reader ticks it by clicking the label.

A single opt-in
The label states exactly what checking the box means.
Show code
<app-checkbox label="Send weekly digest" name="digest" />

Independent options

Stack checkboxes when the choices do not exclude each other, so the reader can tick any combination.

Independent booleans
Each checkbox owns its own state; ticking one leaves the others untouched.
Show code
<div class="d-flex flex-column gap-2">
    <app-checkbox label="Weekly digest" name="pref-digest" checked="true" />
    <app-checkbox label="Product updates" name="pref-product" />
    <app-checkbox label="Security alerts" name="pref-security" checked="true" />
</div>

Round shape

Draw the box round where a tick marks a finished task, and keep the square box everywhere else.

Round (task completion)
The same tick, focus ring and error state as the square box, drawn round.
Show code
<app-checkbox label="Ship the report" name="task-done" shape="AppCheckShape.Circle" checked="true" />

Validation

Helper text gives guidance, and an error replaces it when validation fails, in the same slot below the control.

Helper text and error
Sent every Monday morning.
You must accept the terms.
Show code
<app-checkbox label="Send weekly digest" name="digest" helper-text="Sent every Monday morning." />
<app-checkbox label="Accept terms" name="terms" required="true" error="You must accept the terms." />

Control only

Control only draws just the checkbox, 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-checkbox control-only="true" name="co-agree" value="yes" /> I agree to the terms</label>

Every option

Every value of every prop, one cell each.

state

(default): unchecked
checked="true"
defaultChecked: React only, Razor sets the starting state with checked
indeterminate: React only, set el.indeterminate from your own script
(default): enabled
disabled="true"
(default): editable
read-only="true"
(default): idle
loading="true"

label

label="Send weekly digest"
label omitted: no label row
(content): markup label, Razor only
label="0": falsy but still rendered

help

help: info-tip after the label
help-label="More information" (default)
help-label="Why we ask"

validation

required="true": pass-through, native validation, no visible change
helper-text
Sent every Monday morning.
error
You must accept the terms.
error (replaces helper text)
Ignored while an error is shown.
You must accept the terms.

shape

(default): square box
shape="circle"

size

size="sm"
size="md" (default)
size="lg"

name, id and value

name: sent on submit, no visible change
id: the input's id, no visible change
value: sent on submit when checked, no visible change

onChange

onChange: React only, Razor reads the native change event

controlOnly and className

control-only="true": draws only the box, name it with aria-label
class: extra class on the wrapper, no visible change

ref and asp-for

ref: React only, forwarded to the input
asp-for: binds name, id, checked and label from a page model (this page has none, so the demo sets name)

Guidance

What to do, and what to avoid.

Use it when

  • You need one or more independent true/false settings, where any combination is valid.
  • The user opts in on a form that is saved later (terms, notification preferences).
  • Several options apply at once and are not mutually exclusive.

Reach for something else when

  • One on/off setting that takes effect immediately. → AppSwitch
  • The user must pick exactly one of 2 to 5 options. → AppRadio
  • The user picks many values from a long list. → AppSelect mode="multiple"
  • It is a selectable filter or tag pill. → AppChoiceChip

Independent options each get a checkbox

Do

Independent settings: each checkbox toggles on its own, any combination allowed.

Avoid

Radios force a single choice, so independent yes/no options each need their own checkbox.

Checkboxes, not switches, for saved forms

Do

A clear, specific label states exactly what opting in means.

Avoid

Switches imply an instant, saved effect; on a form that submits on Save, checkboxes set the right expectation.

Reference

Try every prop, read the full list, and check keyboard and screen reader behaviour.

unset circle
unset sm md lg
React, generated from the controls
<AppCheckbox />
Razor, the same props
<app-checkbox />

18 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
labeldefault - string - The clickable label beside the box, HTML-encoded. For markup (e.g. an embedded link), use child content instead. The React equivalent is a ReactNode label.
namedefault - string - The form field name, sent with the value on submit.
checkeddefault false bool false Controlled ticked state; pair with onChange.
helper-textdefault - string - Helper text below the control. Hidden while an error is shown.
disableddefault false bool false Locks the checkbox and dims it.

Less common 13 props

PropTypeDefaultDescription
(content)default - markup - Razor-only. Child content is used as the label verbatim (not encoded) when present, so it can carry markup like a link. Wins over label.
asp-fordefault - ModelExpression - Razor-only. Binds name, id, checked state, label and validation message from the model, via IHtmlGenerator.
iddefault - string - The input's id. A unique id is generated when none is given.
valuedefault - string - Submitted value when checked.
requireddefault - bool - Not a typed attribute on the tag helper. An unclaimed author attribute like this passes through to the rendered input verbatim.
errordefault - string - Error message, rendered below the control. Replaces the helper text.
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 The control size: sm, md or lg.
helpdefault - string - Info-tip content shown beside the label. Shown only when a label is set.
help-labeldefault More information string More information aria-label for the info-tip button.
shapedefault - circle - circle draws a round box with the tick inside, for a task that is completed. Omit it for the square box.
classdefault - string - Extra class on the wrapper around the box and label.

Screen reader

3 notes
  • The label is linked to the input by id, so a click on the label text ticks the box.
  • The error or the helper text is linked to the input with aria-describedby, and an error sets aria-invalid to true.
  • An id is generated when none is given, so the label link always works.

Do and avoid

2 pairs

Independent options each get a checkbox

Do

Independent settings: each checkbox toggles on its own, any combination allowed.

Avoid

Radios force a single choice, so independent yes/no options each need their own checkbox.

Checkboxes, not switches, for saved forms

Do

A clear, specific label states exactly what opting in means.

Avoid

Switches imply an instant, saved effect; on a form that submits on Save, checkboxes set the right expectation.