Usage

Use CheckboxInput for a boolean option or a list of independent choices. The component includes a label, description and status message.

<script setup lang="ts">
import { CheckboxInput } from '@astryx-vue/core/CheckboxInput'
import { shallowRef } from 'vue'

const selected = shallowRef(false)
</script>

<template>
  <CheckboxInput v-model="selected" label="Email updates" />
</template>

Import the theme once in the application entry:

import '@astryx-vue/themes/neutral.css'

Best practices

Guidance	Practices
Do	Always provide a visible label so the user knows what they are toggling. Use isLabelHidden only when surrounding context makes it obvious.
Do	Add a description for choices that need extra context, like explaining what "Share usage data" actually shares.
Do	Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.
Don't	Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.
Don't	Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.
Don't	Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

Examples

Basic selection

Product updates

Receive a monthly summary of new features.

Tips and tutorials

Learn new ways to use the product.

Use v-model to control the selection. Click the label or description to toggle.

Sizes

Small · 20px

Medium · 24px

sm is 20px. md is 24px.

Select all and mixed selection

All notifications

Choose all channels or clear the selection.

Email notifications

Push notifications

The parent shows a mixed state when some items are selected. Activating it changes the value to true.

Disabled, read-only and loading

Read-only selection

Disabled option

Managed by your team

Contact your administrator to change this setting.

Saving preferences

Loading

Email receiptsOptional

Loading blocks repeat activation. Hover or focus the disabled control to read its reason.

Native forms

I accept the termsRequired

Accept the terms before you submit.

This example uses native form validation.

Select the required option before submitting. The reset handler updates v-model.

Async saving and retry

Enable notifications

Changes take one second to save.

Simulate a failed save

The selection stays visible if saving fails. Turn off the simulation and change the selection to retry.

Enable failure simulation to show an error. Turn it off and change the selection to retry.

Keyboard and accessibility

CheckboxInput renders a native <input type="checkbox">, so keyboard behaviour follows the browser defaults: press Tab to focus the checkbox, and press Space to toggle the selection.

The component wires the label, description and status message together through ARIA attributes, so assistive technology reads them as one unit:

• Always provide label; screen readers use it to describe what this option means. isLabelHidden only hides the visual label, and the label text still provides the accessible name.
• aria-describedby references the description and the status message, so both are announced on focus.
• The mixed state comes from the native indeterminate property, which browsers and assistive technology recognise directly.
• isRequired enables the browser's native required validation.
• When the status is an error, the component sets aria-invalid.

For a decorative selection mark on its own, use CheckboxIndicator.