Checkbox

Checkbox is the low-level checkbox control. Use it when you need to compose custom layouts around the checkbox yourself. For the common labeled row pattern, use CheckboxInput.

Basic Usage

Use an accessible name when the checkbox is not paired with visible text in the same component.

Checked

Use checked state for persisted preferences so the current selection reads clearly at a glance.

Disabled

Disable the checkbox when an option is visible for context but currently unavailable. Disabled checkboxes use a muted opacity and disabled cursor.

API

Slots

Name	Description
(default)	Checkbox label text
hint	Descriptive hint (or use the hint attribute)

Attributes & Properties

Name	Description
ariaLabel aria-label	Type string | null Default null
checkboxValue	Type string Default on
checked	Type boolean Default false
customError custom-error	Custom validation message; also settable via setCustomValidity(). Type string | null Default null
defaultChecked default-checked	Type boolean Default false
disabled	Disables the control and excludes it from constraint validation. Type boolean Default false
hint	Descriptive hint — use the hint slot for HTML content. Type string
indeterminate	Type boolean Default false
invalid	Type boolean Default false
name	Name submitted with form data. Type string | null Default null
required	Marks the control as required for form submission. Type boolean Default false
withHint with-hint	Only required for SSR when slotting a hint. Type boolean Default false

Methods

Name	Description
checkValidity()	Runs constraint validation without showing the browser UI.
reportValidity()	Runs constraint validation and shows the browser UI when invalid.
resetValidity()	Clears custom errors and re-syncs validity state.
setCustomValidity(message: string)	Sets or clears a custom validation message.

Events

Name	Description
change	—
input	—
pk-change	—

Custom States

Name	Description	CSS selector
disabled	The control is disabled.	:state(disabled)
invalid	The control currently fails constraint validation.	:state(invalid)
optional	The control is not required.	:state(optional)
required	The control is required.	:state(required)
user-invalid	Invalid after the user has interacted with the control.	:state(user-invalid)
user-valid	Valid after the user has interacted with the control.	:state(user-valid)
valid	The control currently passes constraint validation.	:state(valid)

CSS Parts

Name	Description	CSS selector
base	Root label element	::part(base)
checked-icon	Checked state icon	::part(checked-icon)
control	Visual checkbox box	::part(control)
hint	Hint text container	::part(hint)
indeterminate-icon	Indeterminate state icon	::part(indeterminate-icon)
input	Native checkbox input	::part(input)
label	Label text container	::part(label)