Checkbox

Multi-select form control supporting checked, indeterminate, and disabled states. Ideal for preferences, bulk-selection patterns, and consent forms where users need to toggle one or more independent options.

Components

Checkbox

input

hybrid

<arc-checkbox>

Overview

Checkbox is the standard multi-select form control in ARC UI. Unlike radio groups and toggles, which enforce a single active choice, checkboxes let users select any combination of options independently. This makes them the correct element for settings pages, filter panels, consent agreements, and any context where selections are non-exclusive. The component ships with three visual states: unchecked, checked, and indeterminate. The indeterminate state is particularly useful for "select all" patterns where only some child items are checked, giving users a clear visual signal that the group is partially selected. Toggling an indeterminate checkbox resolves it to fully checked, which is the behavior users expect from file managers and data tables. Every checkbox includes a built-in label, a form-compatible name/value pair, and full keyboard support. Pressing Space toggles the state, and focus-visible rings ensure keyboard users always know which control is active. The disabled state dims the checkbox and prevents interaction, which is useful for options that depend on a prerequisite being met first.

Guidelines

When to use

Use checkboxes when users can select zero, one, or many options from a list
Provide a clear, concise label for every checkbox — never leave them unlabeled
Use the indeterminate state for "select all" controls that govern a partially-checked group
Order checkbox lists logically — alphabetically, by frequency, or by importance
Group related checkboxes together with a visible heading or fieldset legend
Set a default checked state for recommended or common options when appropriate

When not to use

Do not use checkboxes for mutually exclusive choices — use a radio group instead
Do not use a checkbox as an on/off switch for instant actions — use a toggle for that pattern
Do not rely solely on color to communicate checked state; the checkmark icon is essential
Do not disable checkboxes without a nearby explanation of why the option is unavailable
Do not nest checkboxes more than one level deep; flat lists are easier to scan and interact with
Do not use negative label phrasing like "Don't send emails" — prefer affirmative wording

Features

Checked and unchecked toggle with a single click or Space press
Indeterminate (mixed) state for partial "select all" patterns
Built-in label with proper click-to-toggle association
Disabled state that dims the control and blocks interaction
Form-compatible name and value attributes for native submission
Focus-visible ring for keyboard accessibility
Fires `arc-change` event on every state transition
Works standalone or as part of a checkbox group

Preview

Usage

Layout and styling work without JavaScript via the HTML/CSS versions. Interactive features like events and state management require the Web Component or a framework wrapper.

<script type="module" src="@arclux/arc-ui"></script>

<div style="display: flex; flex-direction: column; align-items: flex-start; gap: var(--space-sm);">
  <arc-checkbox label="Set up your profile" checked></arc-checkbox>
  <arc-checkbox label="Connect a repository" checked></arc-checkbox>
  <arc-checkbox label="Invite team members"></arc-checkbox>
  <arc-checkbox label="Configure CI/CD"></arc-checkbox>
</div>

import { Checkbox } from '@arclux/arc-ui-react';

export function OnboardingChecklist() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'flex-start', gap: 'var(--space-sm)' }}>
      <Checkbox label="Set up your profile" checked />
      <Checkbox label="Connect a repository" checked />
      <Checkbox label="Invite team members" />
      <Checkbox label="Configure CI/CD" />
    </div>
  );
}

<script setup>
import { Checkbox } from '@arclux/arc-ui-vue';
</script>

<template>
  <div style="display: flex; flex-direction: column; align-items: flex-start; gap: var(--space-sm);">
    <Checkbox label="Set up your profile" checked />
    <Checkbox label="Connect a repository" checked />
    <Checkbox label="Invite team members" />
    <Checkbox label="Configure CI/CD" />
  </div>
</template>

<script>
  import { Checkbox } from '@arclux/arc-ui-svelte';
</script>

<div style="display: flex; flex-direction: column; align-items: flex-start; gap: var(--space-sm);">
  <Checkbox label="Set up your profile" checked />
  <Checkbox label="Connect a repository" checked />
  <Checkbox label="Invite team members" />
  <Checkbox label="Configure CI/CD" />
</div>

import { Component } from '@angular/core';
import { Checkbox } from '@arclux/arc-ui-angular';

@Component({
  imports: [Checkbox],
  template: `
    <div style="display: flex; flex-direction: column; align-items: flex-start; gap: var(--space-sm);">
      <arc-checkbox label="Set up your profile" checked></arc-checkbox>
      <arc-checkbox label="Connect a repository" checked></arc-checkbox>
      <arc-checkbox label="Invite team members"></arc-checkbox>
      <arc-checkbox label="Configure CI/CD"></arc-checkbox>
    </div>
  `,
})
export class OnboardingChecklistComponent {}

import { Checkbox } from '@arclux/arc-ui-solid';

export function OnboardingChecklist() {
  return (
    <div style={{ display: 'flex', 'flex-direction': 'column', 'align-items': 'flex-start', gap: 'var(--space-sm)' }}>
      <Checkbox label="Set up your profile" checked />
      <Checkbox label="Connect a repository" checked />
      <Checkbox label="Invite team members" />
      <Checkbox label="Configure CI/CD" />
    </div>
  );
}

import { Checkbox } from '@arclux/arc-ui-preact';

export function OnboardingChecklist() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'flex-start', gap: 'var(--space-sm)' }}>
      <Checkbox label="Set up your profile" checked />
      <Checkbox label="Connect a repository" checked />
      <Checkbox label="Invite team members" />
      <Checkbox label="Configure CI/CD" />
    </div>
  );
}

<div style="display: flex; flex-direction: column; align-items: flex-start; gap: var(--space-sm);">
  <arc-checkbox label="Set up your profile" checked></arc-checkbox>
  <arc-checkbox label="Connect a repository" checked></arc-checkbox>
  <arc-checkbox label="Invite team members"></arc-checkbox>
  <arc-checkbox label="Configure CI/CD"></arc-checkbox>
</div>

<!-- Auto-generated by @arclux/prism — do not edit manually -->
<!-- arc-checkbox — self-contained, no external CSS needed -->
<div class="arc-checkbox">

</div>

API

disabled boolean =false: Prevents all pointer and keyboard interaction and applies a dimmed visual treatment. Use this for options that are unavailable due to unmet prerequisites. Pair with a tooltip or helper text to explain why the option is locked.
label string ='': Visible text rendered beside the checkbox. Clicking the label toggles the checkbox, matching native HTML behavior. Keep labels short, affirmative, and action-oriented for the best readability.
name string ='': The form field name submitted when the checkbox lives inside a <form>. Required for native form submission and useful for serializing checkbox group values on the server.
value string ='': The value sent with the form when the checkbox is checked. Defaults to "on" if omitted, matching native checkbox behavior. Set explicit values when multiple checkboxes share the same name to distinguish them in the submitted data.
checked boolean =false: Controls whether the checkbox is in its checked (selected) state. When true, a checkmark icon is rendered inside the box. Bind to this property for two-way state management in frameworks that support it.
indeterminate boolean =false: When true, displays a horizontal dash instead of a checkmark, representing a mixed or partially-selected state. Commonly used on a parent "select all" checkbox when only some children are checked. Clicking an indeterminate checkbox resolves it to fully checked.
size 'sm' | 'md' | 'lg' ='md': Controls the checkbox size.
formAssociated boolean =true
properties object ={ // flag(), unlike `disabled`. The exclusion in props.js is specifically // about form-associated *platform* semantics: a `disabled` content // attribute that is merely present makes the element actually disabled // per the HTML spec, and formDisabledCallback assigns the property back, // so no converter can win. Neither of these is platform-mapped — // `required` is enforced by _computeValidity() below and `readonly` by // each component's own interaction handlers — so the stock converter buys // nothing here and costs the usual bug: `required="false"` read as true, // blocking submission of a form the author meant to leave optional. // Finding #48's shape, across all 26 form controls at once. required: flag(false), readonly: flag(false), }: Lit merges static properties up the prototype chain, so every consumer gets these without declaring them. required participates in constraint validation below; readonly reflects for styling and is enforced by each component's interaction handlers (the mixin can't know which gestures mutate state).
autoValidates boolean =true: Components that run their own constraint-validation logic (pattern checks, range checks) opt out of the automatic required sync by overriding this to false, and own the whole validity flag set instead.
form
validity
validationMessage
required boolean =false
readonly boolean =false

Methods

checkValidity() →boolean: Whether the control currently satisfies its constraints, per the native constraint-validation API. Fires invalid on the element when it does not, and reports nothing to the user.
reportValidity() →boolean: As checkValidity(), but also shows the browser's validation message against the control when it fails.

Events

arc-change detail: { checked: boolean }: Fired when the checked state changes

Checkbox

Overview

Guidelines

When to use

When not to use

Features

Preview

Usage

API

Methods

Events

See Also

Docs

Project

Arclight