Choice & selection

AppCheckbox

A single true/false setting — or several independent ones the user ticks on their own.

<app-checkbox label="Send weekly digest" name="digest" />

A checkbox captures a single yes/no answer — accept the terms, subscribe to a digest, enable a feature. Several checkboxes together capture independent yes/no answers: ticking one never changes another, which is exactly what sets a checkbox apart from a radio.

Its look comes entirely from the shared @webority/theme, so the Razor <app-checkbox> and the React <AppCheckbox> render identically — a checkbox is a checkbox on every Webority surface.

Playground

Every attribute, live. Each change re-renders the real tag helper on the server, so the markup underneath is the exact call that produced the checkbox above it.

<app-checkbox />
indeterminate has no tag-helper attributeThe browser's indeterminate flag is a DOM property, not an HTML attribute, so it can't round-trip through a query-string playground or a server-rendered tag helper — it has to be set imperatively from your own page script after the checkbox renders. See Every option → state.

Label and checked

A checkbox is its label plus its checked state. Bind checked / onChange for a controlled value; the label is what the user clicks.

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 several checkboxes when the choices don't exclude each other — the user can tick any combination, including none or all.

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>

Validation

Show a hint for guidance and an error when validation fails. They share one slot below the control — the error replaces the hint, matching app-input.

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

When to use

Use it when

  • You need one or more independent true/false settings — 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–5 options. → AppRadio
  • The user picks many values from a long list. → AppMultiSelect
  • It is a selectable filter or tag pill. → AppChoiceChip

Best practices

Do
Independent settings — each checkbox toggles on its own, any combination allowed.
Don't
Switches imply an instant, saved effect; on a form that submits on Save, checkboxes set the right expectation.
Do
A clear, specific label states exactly what opting in means.
Don't
Radios force a single choice — independent yes/no options each need their own checkbox.

Every option

The whole surface of the component, one cell per value — including the states a normal example never shows: indeterminate, disabled combinations, and the label edge cases.

state

(default) — unchecked
checked="true"
indeterminate — no attribute; set el.indeterminate from your own script after render
disabled="true"
disabled="true" checked="true"
required="true" — pass-through attribute, not a typed one

label

(no label attribute) — no <label> rendered
label="0" — falsy-but-not-nullish string, still renders
child content — markup label, e.g. an embedded link

validation

hint
Sent every Monday morning.
error (replaces hint)
You must accept the terms.
required + error
Required to continue.

Attributes

AttributeTypeDefaultDescription
labelstring—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.
(content)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-forModelExpression—Razor-only. Binds name, id, checked state, label and validation message from the model, via IHtmlGenerator.
namestring—Field name for form submission; also derives the input id when id is not set.
idstring—Explicit input id — binds the label's for to it and overrides the name-derived id. Declared property, matching React's id. Auto-generated from name / asp-for when omitted.
valuestring—Submitted value when checked.
checkedboolfalseRenders the box in the checked state.
requiredbool—Not a typed attribute on the tag helper — an unclaimed author attribute like this passes through to the rendered <input> verbatim (the same mechanism as React's {...rest}).
errorstring—Error message below the control. Turns aria-invalid true and replaces the hint. Wins over the model's own asp-for validation message.
hintstring—Helper text below the control. Hidden while an error (or a model validation message) is shown.
disabledboolfalseDisables the control. Declared property, matching React's disabled.
shapepill | round | circlepillTrack shape for app-switch only — ignored on app-checkbox. See the AppSwitch page.
classstring—Extra class on the form-check wrapper.