On this page
@addTagHelper *, Webority.Ui.RazorLabel and checked
A checkbox is its label plus its checked state, and the reader ticks it by clicking the label.
Independent options
Stack checkboxes when the choices do not exclude each other, so the reader can tick any combination.
Round shape
Draw the box round where a tick marks a finished task, and keep the square box everywhere else.
Validation
Helper text gives guidance, and an error replaces it when validation fails, in the same slot below the control.
Control only
Control only draws just the checkbox, for a dense form that draws its own labels and messages.
Every option
Every value of every prop, one cell each.
state
(default): uncheckedchecked="true"defaultChecked: React only, Razor sets the starting state with checkedindeterminate: React only, set el.indeterminate from your own script(default): enableddisabled="true"(default): editableread-only="true"(default): idleloading="true"label
label="Send weekly digest"label omitted: no label row(content): markup label, Razor onlylabel="0": falsy but still renderedhelp
help: info-tip after the labelhelp-label="More information" (default)help-label="Why we ask"validation
required="true": pass-through, native validation, no visible changehelper-texterrorerror (replaces helper text)shape
(default): square boxshape="circle"size
size="sm"size="md" (default)size="lg"name, id and value
name: sent on submit, no visible changeid: the input's id, no visible changevalue: sent on submit when checked, no visible changeonChange
onChange: React only, Razor reads the native change eventcontrolOnly and className
control-only="true": draws only the box, name it with aria-labelclass: extra class on the wrapper, no visible changeref and asp-for
ref: React only, forwarded to the inputasp-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
Independent settings: each checkbox toggles on its own, any combination allowed.
Radios force a single choice, so independent yes/no options each need their own checkbox.
Checkboxes, not switches, for saved forms
A clear, specific label states exactly what opting in means.
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.
18 props. The 5 most used come first.
Used on most screens 5 props
| Prop | Type | Default | Description |
|---|---|---|---|
| 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
| Prop | Type | Default | Description |
|---|---|---|---|
| (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 pairsIndependent options each get a checkbox
Independent settings: each checkbox toggles on its own, any combination allowed.
Radios force a single choice, so independent yes/no options each need their own checkbox.
Checkboxes, not switches, for saved forms
A clear, specific label states exactly what opting in means.
Switches imply an instant, saved effect; on a form that submits on Save, checkboxes set the right expectation.