`<bmx-checkbox>`

A single checkbox with the same chrome as the rest of the form family: a caption beside it, optional help text under it, one error message at a time, and real form participation from inside a shadow root.

18 properties · 4 events · 5 methods · 7 parts

Example

Show markup

<div class="row">
  <bmx-checkbox label="Email me about new releases" description="No more than once a month."></bmx-checkbox>
</div>
<div class="row">
  <bmx-checkbox label="Select all" indeterminate="true" description="Mixed: some of the rows below are ticked. Clicking resolves it to ticked."></bmx-checkbox>
</div>
<div class="row">
  <bmx-checkbox label="I accept the terms" required="true" description="Tab away without ticking it to see when it speaks up."></bmx-checkbox>
</div>
<div class="row">
  <bmx-checkbox label="Ticked" checked="true"></bmx-checkbox>
  <bmx-checkbox label="Disabled" disabled="true"></bmx-checkbox>
  <bmx-checkbox label="Disabled and ticked" checked="true" disabled="true"></bmx-checkbox>
</div>

It also carries the third state. indeterminate is what the parent of a partly-ticked list shows, and it is a state rather than a value: an indeterminate box submits exactly what an unticked one submits, which is nothing. Clicking it resolves it to ticked, as the platform does.

WHY THE BOX YOU SEE IS NOT THE INPUT

The <input> is real, focusable and form-associated, and it fills the whole 24-pixel target invisibly; what you see is drawn beside it. Two things follow that a styled appearance: none input cannot give you.

The first is the target itself. WCAG 2.2 SC 2.5.8 asks for 24x24 CSS pixels, and a tick box drawn at the size people expect one to be is 18 to 20. Padding an input does not help - its border sits outside the padding, so the box would be drawn at the full 24 - and the alternative reading of the criterion, that the caption makes the target big enough, stops being true the moment somebody sets hide-label.

The second is the mark. A tick that has to work at five sizes and ten themes is a stroked path with a stroke-dasharray animation on it, and that is not something an input's own rendering will ever do.

Properties

Property	Attribute	Type	Default	Description
`autoFocus`	`auto-focus`	`boolean`	`false`	Focus the box once it has rendered.
`checked`	`checked`	`boolean`	`false`	Whether the box is ticked. Two-way: the component writes back to it.
`description`	`description`	`string`	—	Help text below the row.
`disabled`	`disabled`	`boolean`	`false`	Disable the box.
`errorText`	`error-text`	`string`	—	An error supplied by the consumer - a server response, typically.
`fullWidth`	`full-width`	`boolean`	`false`	Stretch to the width of the container, pushing the caption away from the box.
`hideLabel`	`hide-label`	`boolean`	`false`	Hide the caption visually while keeping it as the accessible name.
`indeterminate`	`indeterminate`	`boolean`	`false`	The mixed state. Visual and semantic only - `aria-checked="mixed"` and a dash in place of the tick. It never submits, and any user interaction clears it.
`label`	`label`	`string`	—	The caption. Required unless the `label` slot is used.
`labelPlacement`	`label-placement`	`BmxCheckboxLabelPlacement`	`'end'`	Which side of the box the caption sits on. Logical, so RTL flips it.
`messages`	property only	`BmxFieldMessages`	—	Replacements for the default wording, by reason. Accepts the JSON spelling of the object as well, for templates that can only write attributes. See `src/core/markup.ts`.
`name`	`name`	`string`	—	The field's name in the form it belongs to.
`required`	`required`	`boolean`	`false`	Require the box to be ticked before its form will submit.
`shape`	`shape`	`BmxShape`	`'rounded'`	Corner treatment of the box. `pill` and `circle` both round it fully.
`size`	`size`	`BmxSize`	`'md'`	Size step. Scales the box, the caption and the supporting text together.
`tone`	`tone`	`BmxTone`	`'primary'`	Semantic colour role for the ticked state and the focus ring.
`validateOn`	`validate-on`	`BmxValidateOn`	`'blur'`	When the field is willing to reveal a problem.
`value`	`value`	`string`	`'on'`	What the form receives when the box is ticked. Matches the native default.

Events

Event	Detail	Description
`bmxBlur`	`void`	Fired when the box loses focus.
`bmxChange`	`BmxCheckboxChangeDetail`	Fired when the ticked state changes, by user action or by `toggle()`.
`bmxFocus`	`void`	Fired when the box gains focus.
`bmxValidityChange`	`BmxCheckboxValidityDetail`	Fired whenever the resolved validity changes.

Methods

Method	Signature	Description
`checkValidity`	`checkValidity() => Promise<boolean>`	Validate now and return whether the box passed, without revealing anything.
`removeFocus`	`removeFocus() => Promise<void>`	Remove focus from the box.
`reportValidity`	`reportValidity() => Promise<boolean>`	Validate, reveal any problem, and focus the box if it has one.
`setFocus`	`setFocus(options?: FocusOptions) => Promise<void>`	Focus the box.
`toggle`	`toggle() => Promise<void>`	Move to the next state, as a click would. Including from indeterminate, which resolves to ticked. Does nothing while the box is disabled, so a consumer's "toggle all" cannot quietly change a value the user has been told they may not change.

Slots

Slot	Description
`description`	Rich help text, in place of the `description` property.
`label`	Rich caption content, in place of the `label` property.

CSS shadow parts

Part	Description
`base`	The row holding the box and its caption.
`box`	The wrapper around the control and the drawn mark.
`control`	The native checkbox.
`description`	The help text.
`error`	The error message.
`label`	The caption.
`mark`	The drawn box and tick.

CSS custom properties

Property	Description
`--bmx-checkbox-background`	The box's background when unticked.
`--bmx-checkbox-border-color`	The box's border colour when unticked.
`--bmx-checkbox-border-width`	Border width of the box in its unticked state.
`--bmx-checkbox-checked-background`	The box's background when ticked or mixed. Defaults to the tone's solid colour.
`--bmx-checkbox-duration`	How long the tick takes to draw. Zero under reduced motion.
`--bmx-checkbox-font-size`	The caption's font size.
`--bmx-checkbox-gap`	Space between the box and its caption.
`--bmx-checkbox-mark-color`	The tick and dash colour.
`--bmx-checkbox-radius`	Corner radius of the box.
`--bmx-checkbox-size`	The drawn box's width and height. The clickable target stays at least 24px regardless.
`--bmx-checkbox-support-font-size`	Font size of the description and error message.