CheckboxField

<caos-checkbox-field>

a boolean field

May be placed on a record page, a page inside an app and a step of a guided flow.

Inputs

Name	Attribute	Description	Type	Default	Required
checked	checked, also a property	The box is ticked. It reflects — the piece writes it back on itself when the person toggles, so reading the attribute is reading the current state.	boolean	false	Optional
indeterminate	indeterminate, also a property	The mixed state: a dash rather than a tick, announced as “mixed”. For a box that stands for a group where only some are on. It is cleared on the first interaction and does not come back on its own.	boolean	false	Optional
disabled	disabled, markup only	You may not change this. Fades the row, refuses the toggle and takes the box out of the tab order.	boolean	false	Optional
required	required, markup only	This box has to be ticked. Draws the asterisk after the label and marks the box required.	boolean	false	Optional
invalid	invalid, markup only	The answer is wrong — usually a required box left unticked. Turns the box outline, its fill and the message red, and marks the box invalid for a screen reader.	boolean	false	Optional
message	message, markup only	The line under the row, indented to sit under the label rather than under the box. Muted helper text on its own; the red reason when invalid is also set.	text	none declared	Optional
inline	inline, markup only	Draw the record-detail variant: a smaller box on its own, with the label and the message hidden because the surrounding record detail supplies the field name. Unlike the other fields, this one has no click-to-reveal step in that mode — the box is already its own affordance.	boolean	false	Optional

Events

Name	When it fires	What it carries
change	When the box is toggled — by a click anywhere on the row, or Space or Enter on the box — and never when the page sets checked itself.	nothing

Slots

Name	What goes in it
the default slot	The label text beside the box. This is where the label goes; the attribute is not read.

Styling hooks

Design token	What it controls
--caos-space-2	The gap between the box and the label, and the indent of the message.
--caos-space-1	The gap above the message.
--caos-radius-sm	The corner radius of the box.
--caos-color-border	The outline of an unticked box.
--caos-color-surface	The fill of an unticked box.
--caos-color-accent	The outline of a box on hover and when it has keyboard focus.
--caos-color-accent-fill	The fill and outline of a ticked or mixed box.
--caos-color-accent-contrast	The tick and the dash drawn on that fill. White by default; a brand with a pale accent sets a darker ink here.
--caos-color-danger-fill	The fill of a ticked or mixed box that is invalid.
--caos-color-danger-contrast	The tick and the dash drawn on that invalid fill.
--caos-focus-ring	The ring drawn around the box when it has keyboard focus.
--caos-color-danger	The required asterisk, and the box and message when invalid.
--caos-font	The typeface of the label and the message.
--caos-text-body	The size of the label.
--caos-color-text	The colour of the label.
--caos-color-text-muted	The colour of the message.

Methods

Name	Description	Arguments
focus()	Move keyboard focus to the box, so Space toggles it. The record-detail editor calls it when a value is clicked to edit.	options: FocusOptions

Readable state

Nothing on this piece can be read back.

Styling parts

Part	Which piece of it	When it is there
::part(control)	the clickable row, box and label together	Always
::part(box)	the drawn box	Always
::part(label)	the label beside the box	Always
::part(message)	the line under the row	Always

When to use it

One independent yes-or-no answer, where both answers are ordinary. If ticking it commits something or takes effect immediately rather than being saved with the rest of the form, say so in the label.

What to use instead

• FieldRenderer — The type is not known until the record is read — hand it the field metadata and it draws the right control, including a multi-select edited as a group of these.
• SegmentedFilter — The choice changes what is shown rather than recording an answer.
• PicklistField — There are more than a couple of options and only one may be chosen.
• StatusPill — The yes-or-no is being reported rather than answered, and cannot be changed here.

Accessibility

The box is a real focusable control with role="checkbox", and everything a native one gives is wired to match: Space and Enter toggle it, clicking anywhere on the row toggles it, aria-checked reports true, false or mixed, aria-required and aria-invalid follow their attributes, and a disabled box reports aria-disabled and drops out of the tab order rather than staying focusable and inert. What is left to the author is the LABEL, which has to be the content — an empty element is an unnamed checkbox with nothing to announce — and, for a set of these, a name for the set on whatever holds them.

Examples

Ticked and unticked

The two ordinary states, with the label written where the piece reads it — as the content, not as an attribute.

{
  "id": "example",
  "section": "Ticked and unticked",
  "columns": 1,
  "items": [
    {
      "id": "checkbox_field_1",
      "type": "component",
      "key": "checkbox_field",
      "inputs": {
        "checked": true
      },
      "children": [
        "Send a receipt"
      ]
    },
    {
      "id": "checkbox_field_2",
      "type": "component",
      "key": "checkbox_field",
      "children": [
        "Notify the account owner"
      ]
    }
  ]
}

<caos-checkbox-field checked>Send a receipt</caos-checkbox-field>
<caos-checkbox-field>Notify the account owner</caos-checkbox-field>

Mixed

A box standing for a group where only some are on: a dash instead of a tick, announced as mixed. It looks like the ticked state and means something different, which is why it is its own example.

{
  "id": "example",
  "section": "Mixed",
  "columns": 1,
  "items": [
    {
      "id": "checkbox_field_1",
      "type": "component",
      "key": "checkbox_field",
      "inputs": {
        "indeterminate": true
      },
      "children": [
        "All line items received"
      ]
    }
  ]
}

<caos-checkbox-field indeterminate>All line items received</caos-checkbox-field>

Required and refused

A box that has to be ticked and has not been — the asterisk, the red box, and the reason underneath.

{
  "id": "example",
  "section": "Required and refused",
  "columns": 1,
  "items": [
    {
      "id": "checkbox_field_1",
      "type": "component",
      "key": "checkbox_field",
      "inputs": {
        "required": true,
        "invalid": true,
        "message": "Approval is required before this order can be submitted."
      },
      "children": [
        "Manager approval"
      ]
    }
  ]
}

<caos-checkbox-field required invalid message="Approval is required before this order can be submitted.">Manager approval</caos-checkbox-field>