Checkbox

Checkboxes allow users to select one or more options from a set, or toggle a single binary choice. Supports indeterminate state for partial selection patterns.

Properties

Name	Type	Default	Description
`theme`	`'light' \| 'dark'`	`'dark'`	Per-component theme override. Sets data-theme on the host element so token overrides cascade into Shadow DOM.
`label`	`string`	`''`	Visible label text rendered next to the checkbox. Also provides the accessible name for screen readers.
`name`	`string`	`''`	Field name. Emitted in the update event detail. Use for identifying the field in form data.
`value`	`string`	`'on'`	Value emitted in the update event detail when the checkbox is checked.
`checked`	`boolean`	`false`	Whether the checkbox is checked. Mutable — the component updates this prop on user interaction and also emits an update event.
`indeterminate`	`boolean`	`false`	Shows a dash icon and sets aria-checked="mixed". Visually overrides checked. Cleared automatically when the user clicks.
`disabled`	`boolean`	`false`	Disables interaction and reduces opacity to 0.4. The native input receives the disabled attribute.
`required`	`boolean`	`false`	Marks the field as required with a visual asterisk in the label. Passed to the native input.
`state`	`'none' \| 'error' \| 'success'`	`'none'`	Validation state. Changes the checkbox border colour and message text colour.
`message`	`string`	`''`	Helper or validation message. Only rendered when state is "error" or "success". Linked to the input via aria-describedby.
`compact`	`boolean`	`false`	Enables dense mode. Reduces checkbox size from 20 px to 14 px for dense layouts.
`hide-label`	`boolean`	`false`	Hides the label visually using a sr-only clip pattern. The label text is still announced by screen readers.

Events

Name	Detail type	Bubbles	Description
`update`	`{ checked: boolean; name: string; value: string }`	No	Emitted when the user toggles the checkbox. `detail.checked` is the new state. React consumers: use the lowercase `onupdate` prop (React 19 custom element event name mapping does not lowercase the event name).

Slots

diwa-checkbox has no slots. The label is provided via the label prop.

CSS custom properties

Override these tokens on the host element or a parent selector to customise the checkbox without modifying source styles.

Property	Fallback	Description
`--diwa-border`	zinc-700 (dark) / zinc-300 (light)	Default border colour of the unchecked checkbox box.
`--diwa-accent`	#10a37f	Fill and border colour of the checked and indeterminate states.
`--diwa-accent-hover`	#0e9470	Fill colour when hovering over a checked checkbox.
`--diwa-bg-hover`	zinc-800 (dark) / rgba(148,149,152,0.18) (light)	Background tint applied on hover of an unchecked checkbox.
`--diwa-notification-error`	#ef4444 (dark) / #cc1922 (light)	Border colour when state="error".
`--diwa-notification-success`	#22c55e (dark) / #197e10 (light)	Border colour when state="success".
`--diwa-text-primary`	#e6e6e7 (dark) / #010205 (light)	Label text colour.
`--diwa-font-size-sm`	11px	Font size of the message text beneath the checkbox.

Form submission (V1 limitation): The inner <input name> lives inside Shadow DOM and is not visible to ancestor <form> elements for native submission. Collect checkbox values via the update event and submit programmatically. Native form participation via ElementInternals is planned for V2.