A Boolean form control with an inline label, a mixed state and native form participation.
<tp-checkbox>
Checkbox
Default density
Compact density
Restart from the initial state
Show the copyable source
Accept the terms of service
Accept the terms of service
<tp-checkbox name="terms" default-checked>Accept the terms of service</tp-checkbox>
Usage
The default slot is the Checkbox’s inline label, and clicking it toggles the box. Pointer and Space toggle; Enter does not, so a Checkbox never fights a form’s submit key. Native HTML labels activate this same Boolean owner: use a wrapping label or a for matching the Checkbox host’s id.
With a Field
Put a Checkbox in tp-field when it needs a description or error. The Field supplies the accessible name and shows validation for required, which is satisfied only when checked.
Field
Default density
Compact density
Restart from the initial state
Show the copyable source
<tp-field label="Email me product updates" description="About one email a month. Unsubscribe anytime." style="max-inline-size:22rem;margin-inline:auto">
<tp-checkbox name="updates" value="monthly"></tp-checkbox>
</tp-field>
Forms
A checked box submits name=value (value defaults to on). An unchecked box submits nothing unless you set unchecked-value, which helps when the server expects an explicit off value. Reset restores default-checked. Native reset restores the latest uncontrolled default with form-reset; controlled reset does not change or notify the owner.
Form values
Default density
Compact density
Restart from the initial state
Show the copyable source
indeterminate shows a mixed indicator, typically on a “select all” box whose children are partly checked. A press always proposes checked, and your code clears the mixed state, because only it knows what the children hold.
Select all
Default density
Compact density
Restart from the initial state
Show the copyable source
For a plain list with a “select all” box, CheckboxGroupController does the bookkeeping above for you. Bind it to an authored fieldset that holds a parent checkbox and valued children; it shows the parent as checked or mixed, checks or clears every enabled child when the parent is pressed, and keeps the group’s value as a list. Each child still submits under its own name. Call group.disconnect() when the fieldset is removed. Options and writable properties are value (controlled string list), defaultValue (empty), allValues, disabled (false), and onValueChange. setValue(list, reason?, event?), reset(event?), refresh(), and disconnect() are public. allValues reports registered child values when omitted; parent aggregation is activated only by explicitly supplying it.
States
Disabled and read-only
Default density
Compact density
Restart from the initial state
Show the copyable source
Two-factor authenticationSingle sign-on (enforced by your admin)Audit logging
Two-factor authenticationSingle sign-on (enforced by your admin)Audit logging
<div style="display:grid;gap:var(--tp-space-3)">
<tp-checkbox disabled>Two-factor authentication</tp-checkbox>
<tp-checkbox disabled default-checked>Single sign-on (enforced by your admin)</tp-checkbox>
<tp-checkbox readonly default-checked>Audit logging</tp-checkbox>
</div>
Disabled boxes leave the tab order and omit their value from form data. Read-only boxes stay focusable and submit their value, but ignore presses.
Controlled
Set checked before first render to own the state. Each press then emits a cancelable tp-value-change; assign checked from event.detail.value to accept it, or leave it unchanged to reject it.
variant="inline" fits the Checkbox into one row the height of a control, with its label at the start and the box at the end, so it stacks with other inline controls such as an inline Select. A press anywhere on the row toggles it. Inside a Field and without a label of its own, the Field’s label moves into the row.
API Reference
Every element also accepts motion-policy.
Attributes
AttributePropertyTypeDefaultDescriptioncheckedcheckedboolean—Whether the box is checked. Set it to own the state: the box then proposes changes and shows
only what you assign.default-checkeddefaultCheckedboolean | undefined—The checked state at first render and after a form reset, when the page does not own checked.indeterminateindeterminateboolean—Shows the mixed state, as on a select-all box whose children are partly checked; a press
proposes checked, and your code clears it.unchecked-valueuncheckedValuestring | undefined—The value submitted while unchecked; without it an unchecked box submits nothing.native-actionnativeActionbooleanfalseRenders the control as a native button instead of a span, for a form layout that expects one.parentparentbooleanfalseMakes this the select-all box of a checkbox group: checked when every child is, mixed when some
are, and pressing it checks or clears them all.keep-mountedkeepMountedbooleanfalseKeeps the hidden check mark in the tree while unchecked, so a custom style can transition it
out.identifieridentifierstring''The id of the inner control, for references from outside the element; generated when empty.variantvariantCheckboxVariant'default'inline shows the label and the box in one compact control-height row, for stacked controls;
without a label of its own, an enclosing Field's label moves into the row.
Properties
PropertyTypeDefaultDescriptiononCheckedChange((event: TpValueChangeEvent<boolean>) => void) | undefined—Called with each proposed change before it commits; assign checked to accept it or cancel the
event to reject it.checkboxGroupCheckboxGroupController | null—The checkbox group that owns this box's state, if any; set by the group itself.checkboxDisabledread-onlyboolean—Whether the box is disabled, by itself, its Field or its checkbox group.controlElementread-onlyHTMLElement | null—The inner element that carries the checkbox role and receives focus.
Events
EventTypeDescriptiontp-value-changeTpValueChangeEvent<boolean>Cancelable proposal of a new checked state before it commits; detail.value, detail.previousValue and the detail.reason for the change.tp-field-valueCustomEvent<{ value: boolean; previousValue: boolean; reason: ChangeReason; }>After the checked state commits, with the same value, previousValue and reason; the enclosing Field listens for it.
Methods
MethodReturnsDescriptionsetChecked(value, reason, source?)voidProposes a new checked state as if the user had made it, notifying listeners first; a box in a
checkbox group ignores it.
Slots
SlotDescriptiondefaultThe inline label; a press on it toggles the box.
CSS parts
PartDescription::part(checkbox)The control with the checkbox role around the box and the label; it receives focus and presses, and is the row of an inline Checkbox.::part(checkbox-indicator)The check or mixed mark inside the box, shown while checked or mixed.
Related
Components, widgets and patterns that use this one.