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

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.
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.
size 'sm' | 'md' | 'lg' ='md': Controls the checkbox size.
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.
formAssociated boolean =true
properties object ={ required: { type: Boolean, reflect: true }, readonly: { type: Boolean, reflect: true }, }: 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

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

Events

See Also

Docs

Project

Arclight