Props

Property	Type	Default	Description
v-model	boolean | 'indeterminate'	—	Required. The current selection.
label	string	—	Required. The accessible name.
id	string	—	Native input ID. Generated when omitted.
size	'sm' | 'md'	'md'	sm is 20px. md is 24px.
width	number | string	—	Component width. Numbers use pixels.
description	string	—	Description below the label.
isLabelHidden	boolean	false	Visually hides the label. Preserves its accessible name.
isDisabled	boolean	false	Prevents changes. Excludes the field from form submission.
disabledMessage	string	—	Disabled reason. Keeps the disabled control focusable.
isReadOnly	boolean	false	Prevents changes. Checked fields still submit.
isLoading	boolean	false	Shows loading. Blocks repeat activation.
loadingLabel	string	'Loading'	Accessible loading text.
isRequired	boolean	false	Shows the required marker. Enables native required validation.
isOptional	boolean	false	Shows the optional marker. Takes precedence over isRequired.
optionalLabel	string	'Optional'	Optional marker text.
requiredLabel	string	'Required'	Required marker text.
htmlName	string	—	Form field name. Overrides native name.
status	FieldStatusInput	—	Status type, message and message ID.
labelIcon	Component	—	Decorative icon before the label.
labelTooltip	string	—	Tooltip for the information button beside the label.
changeAction	CheckboxInputChangeAction	—	Action after a selection change. Supports a Promise.
hasAutoFocus	boolean	false	Focuses the input after mounting.

Status messages

status contains these fields:

• type: 'error', 'warning' or 'success'.
• message: optional message text.
• messageId: optional message ID.

Messages appear below the checkbox. Errors use assertive announcements. Warnings and successes use polite announcements.

Events

• update:modelValue(value): emits a boolean after activation.
• change(value, event): fires after the model update.
• actionError(error, value, event): fires when an action rejects or throws.

event is a cancelable CheckboxInputChangeEvent. event.detail.originalEvent contains the native event. Call event.preventDefault() in change to skip changeAction. This does not undo the model update.

Async actions

changeAction(value, event) receives the new value and component event.

• Returning a Promise shows the loading state.
• Pending actions block repeat activation.
• Explicit parent updates override the temporary selection.
• Loading clears after success or failure.
• Failures do not revert values written to v-model.
• Use @action-error to show failure information.
• Update the bound value in application code if you need a rollback.

Native forms

• htmlName or name sets the field name.
• Native value sets the submitted value. The default is 'on'.
• value does not control selection. Use v-model for selection.
• Unchecked and indeterminate fields do not submit.
• Checked read-only fields submit.
• Disabled fields do not submit.
• Fields with a disabled reason use aria-disabled and have no native form owner.
• isOptional overrides isRequired. An explicit native required attribute still applies.

After form.reset(), the component restores the current v-model. To clear the selection, update the bound value in the form's reset handler.

Template references and attributes

• element: HTMLInputElement | null.
• focus(options?: FocusOptions): focuses the input.
• blur(): removes input focus.
• class and style apply to the outer component.
• Undeclared native attributes and events pass to input.
• aria-labelledby and aria-describedby merge with internal IDs.
• The component owns checked, indeterminate, type and core ARIA states.

Slots

• labelIcon: a decorative icon before the label. Overrides the labelIcon prop.

Theme

.my-checkbox {
  --astryx-checkbox-accent: #047857;
  --astryx-checkbox-on-accent: #fff;
  --astryx-checkbox-focus: #047857;
}

• --astryx-checkbox-background: unchecked background.
• --astryx-checkbox-border: unchecked border.
• --astryx-checkbox-accent: checked and indeterminate background.
• --astryx-checkbox-on-accent: selection mark color.
• --astryx-checkbox-focus: keyboard focus color.
• --astryx-checkbox-disabled-background: disabled unchecked background.
• --astryx-radius-inner: indicator corner radius.

Neutral follows color-scheme. Set data-astryx-color-mode="light" or "dark" to choose a mode.