Checkbox

Multi-select form control with checked, indeterminate, and disabled states. For preferences, bulk selection, and consent forms where users toggle one or more independent options.

Components

Checkbox

input

hybrid

<arc-checkbox>

Overview

Checkbox is the multi-select form control in ARC UI. Unlike radio groups, which allow only one active choice, checkboxes let users select any combination of options independently. Use them for settings pages, filter panels, consent agreements, and any context where selections are not exclusive. The component has three visual states: unchecked, checked, and indeterminate. Indeterminate suits "select all" patterns where only some child items are checked, and shows that the group is partially selected. Toggling an indeterminate checkbox resolves it to checked, as in file managers and data tables. Every checkbox includes a label, a form-compatible name/value pair, and keyboard support. Space toggles the state, and a focus-visible ring shows keyboard users which control is active. The disabled state dims the checkbox and prevents interaction, which suits options that depend on a prerequisite.

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, and never leave one 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 matters
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
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

disabledboolean=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.
labelstring='': 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.
namestring='': 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.
valuestring='': 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.
checkedboolean=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.
indeterminateboolean=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.
formAssociatedboolean=true
propertiesobject={ // 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).
autoValidatesboolean=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
requiredboolean=false
readonlyboolean=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-changedetail:{ 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