Checkbox

A clickable input that lets users make binary choices or select multiple options.

import { component$, useStyles$ } from "@builder.io/qwik";
import { Checkbox } from "@kunai-consulting/qwik";

export default component$(() => {
  useStyles$(styles);

  return (
    <Checkbox.Root>
      <Checkbox.Trigger class="checkbox-trigger">
        <Checkbox.Indicator class="checkbox-indicator">
          <LuCheck />
        </Checkbox.Indicator>
      </Checkbox.Trigger>
    </Checkbox.Root>
  );
});

import { LuCheck } from "@qwikest/icons/lucide";
// example styles
import styles from "./checkbox.css?inline";

Features

WAI ARIA Checkbox design pattern
Indeterminate state support (tri-state)
Form integration with hidden native input
Error message handling and validation
Custom descriptions with ARIA support
Keyboard navigation and accessibility
Controllable checked state (controlled/uncontrolled)
Focus management with ref tracking
Disabled state handling
Enter key prevention for form submissions

Anatomy

Part	Description
<Checkbox.Root>	Root component that provides context and state management for the checkbox
<Checkbox.Indicator>	Visual indicator component showing the checkbox state
<Checkbox.Trigger>	Interactive trigger component that handles checkbox toggling
<Checkbox.Label>	Label component for the checkbox
<Checkbox.Description>	A component that renders the description text for a checkbox
<Checkbox.HiddenInput>	A hidden native checkbox input for form submission
<Checkbox.ErrorMessage>	A component that displays error messages for a checkbox

Examples

Basic Usage

The most basic checkbox implementation requires a Checkbox.Root component with a Checkbox.Trigger and Checkbox.Indicator nested inside.

import { component$, useStyles$ } from "@builder.io/qwik";
import { Checkbox } from "@kunai-consulting/qwik";
import { LuCheck } from "@qwikest/icons/lucide";

export default component$(() => {
  useStyles$(styles);

  return (
    <Checkbox.Root checked>
      <Checkbox.Trigger class="checkbox-trigger">
        <Checkbox.Indicator class="checkbox-indicator">
          <LuCheck />
        </Checkbox.Indicator>
      </Checkbox.Trigger>
    </Checkbox.Root>
  );
});

// example styles
import styles from "./checkbox.css?inline";

The checked prop on Checkbox.Root sets the initial checked state. When checked, the Checkbox.Indicator becomes visible.

Visual Features

Labels and Descriptions

Add descriptive text with Checkbox.Label and Checkbox.Description components. The isDescription prop on Checkbox.Root enables description support.

I accept the Terms and Conditions

By checking this box, you acknowledge that you have read, understood, and agree to our Terms of Service and Privacy Policy. This includes consent to process your personal data as described in our policies.

import { component$, useStyles$ } from "@builder.io/qwik";
import { Checkbox } from "@kunai-consulting/qwik";
import { LuCheck } from "@qwikest/icons/lucide";

export default component$(() => {
  useStyles$(styles);

  return (
    <Checkbox.Root description>
      <div
        style={{ display: "flex", alignItems: "center", gap: "8px", marginBottom: "8px" }}
      >
        <Checkbox.Trigger class="checkbox-trigger">
          <Checkbox.Indicator class="checkbox-indicator">
            <LuCheck />
          </Checkbox.Indicator>
        </Checkbox.Trigger>
        <Checkbox.Label>I accept the Terms and Conditions</Checkbox.Label>
      </div>
      <Checkbox.Description style={{ color: "#b8c1cc" }}>
        By checking this box, you acknowledge that you have read, understood, and agree to
        our Terms of Service and Privacy Policy. This includes consent to process your
        personal data as described in our policies.
      </Checkbox.Description>
    </Checkbox.Root>
  );
});

// example styles
import styles from "./checkbox.css?inline";

Mixed State

Checkboxes support an indeterminate state using the "mixed" value. This is useful for parent/child checkbox relationships.

import { component$, useSignal, useStyles$ } from "@builder.io/qwik";
import { Checkbox } from "@kunai-consulting/qwik";
import { LuCheck, LuMinus } from "@qwikest/icons/lucide";

export default component$(() => {
  useStyles$(styles);

  const isChecked = useSignal<boolean | "mixed">("mixed");

  return (
    <Checkbox.Root bind:checked={isChecked}>
      <Checkbox.Trigger class="checkbox-trigger">
        <Checkbox.Indicator class="checkbox-indicator">
          {isChecked.value === "mixed" ? <LuMinus /> : <LuCheck />}
        </Checkbox.Indicator>
      </Checkbox.Trigger>
    </Checkbox.Root>
  );
});

// example styles
import styles from "./checkbox.css?inline";

Advanced Usage

Form Integration

For form submissions, add Checkbox.HiddenInput to create a native checkbox input. Use name and value props to control form data.

import { component$, useSignal, useStyles$ } from "@builder.io/qwik";
import { Checkbox } from "@kunai-consulting/qwik";
import { LuCheck } from "@qwikest/icons/lucide";

export default component$(() => {
  useStyles$(styles);

  const formData = useSignal<Record<string, FormDataEntryValue>>();

  return (
    <form
      preventdefault:submit
      onSubmit$={(e) => {
        const form = e.target as HTMLFormElement;
        formData.value = Object.fromEntries(new FormData(form));
      }}
      style={{ display: "flex", flexDirection: "column", gap: "8px" }}
    >
      <TermsCheckbox />
      <button type="submit">Submit</button>
      {formData.value && <div>Submitted: {JSON.stringify(formData.value, null, 2)}</div>}
    </form>
  );
});

export const TermsCheckbox = component$(() => {
  return (
    <Checkbox.Root name="terms">
      <Checkbox.HiddenInput />
      <div style={{ display: "flex", alignItems: "center", gap: "8px" }}>
        <Checkbox.Trigger class="checkbox-trigger">
          <Checkbox.Indicator class="checkbox-indicator">
            <LuCheck />
          </Checkbox.Indicator>
        </Checkbox.Trigger>
        <Checkbox.Label>I accept the Terms and Conditions</Checkbox.Label>
      </div>
    </Checkbox.Root>
  );
});

// example styles
import styles from "./checkbox.css?inline";

The required prop enforces validation:

import {
  type Signal,
  component$,
  useComputed$,
  useSignal,
  useStyles$
} from "@builder.io/qwik";
import { Checkbox } from "@kunai-consulting/qwik";
import { LuCheck } from "@qwikest/icons/lucide";

export default component$(() => {
  useStyles$(styles);

  const formData = useSignal<Record<string, FormDataEntryValue>>();
  const isChecked = useSignal(false);
  const isSubmitAttempt = useSignal(false);
  const isError = useComputed$(() => !isChecked.value && isSubmitAttempt.value);

  return (
    <form
      preventdefault:submit
      noValidate
      onSubmit$={(e) => {
        const form = e.target as HTMLFormElement;
        if (!isChecked.value) {
          isSubmitAttempt.value = true;
          return;
        }

        formData.value = Object.fromEntries(new FormData(form));
      }}
      style={{ display: "flex", flexDirection: "column", gap: "8px" }}
    >
      <TermsCheckbox isChecked={isChecked} isError={isError} />
      <button type="submit">Submit</button>
      {formData.value && <div>Submitted: {JSON.stringify(formData.value, null, 2)}</div>}
    </form>
  );
});

type TermsCheckboxProps = {
  isChecked: Signal<boolean>;
  isError: Signal<boolean>;
};

export const TermsCheckbox = component$(({ isChecked, isError }: TermsCheckboxProps) => {
  return (
    <Checkbox.Root name="terms" required bind:checked={isChecked}>
      <Checkbox.HiddenInput />
      <div
        style={{ display: "flex", alignItems: "center", gap: "8px", marginBottom: "8px" }}
      >
        <Checkbox.Trigger class="checkbox-trigger">
          <Checkbox.Indicator class="checkbox-indicator">
            <LuCheck />
          </Checkbox.Indicator>
        </Checkbox.Trigger>
        <Checkbox.Label>I accept the Terms and Conditions</Checkbox.Label>
      </div>
      {isError.value && (
        <Checkbox.ErrorMessage style={{ color: "red" }}>
          Please accept the terms and conditions
        </Checkbox.ErrorMessage>
      )}
    </Checkbox.Root>
  );
});

// example styles
import styles from "./checkbox.css?inline";

You can customize the submitted value using the value prop:

import { component$, useSignal, useStyles$ } from "@builder.io/qwik";
import { Checkbox } from "@kunai-consulting/qwik";
import { LuCheck } from "@qwikest/icons/lucide";

export default component$(() => {
  useStyles$(styles);

  const formData = useSignal<Record<string, FormDataEntryValue>>();

  return (
    <form
      preventdefault:submit
      onSubmit$={(e) => {
        const form = e.target as HTMLFormElement;
        formData.value = Object.fromEntries(new FormData(form));
      }}
      style={{ display: "flex", flexDirection: "column", gap: "8px" }}
    >
      <TermsCheckbox />
      <button type="submit">Submit</button>
      {formData.value && <div>Submitted: {JSON.stringify(formData.value, null, 2)}</div>}
    </form>
  );
});

export const TermsCheckbox = component$(() => {
  return (
    <Checkbox.Root name="terms" value="checked">
      <Checkbox.HiddenInput />
      <div style={{ display: "flex", alignItems: "center", gap: "8px" }}>
        <Checkbox.Trigger class="checkbox-trigger">
          <Checkbox.Indicator class="checkbox-indicator">
            <LuCheck />
          </Checkbox.Indicator>
        </Checkbox.Trigger>
        <Checkbox.Label>I accept the Terms and Conditions</Checkbox.Label>
      </div>
    </Checkbox.Root>
  );
});

// example styles
import styles from "./checkbox.css?inline";

Error Handling

Display error messages using the Checkbox.ErrorMessage component. This automatically sets the appropriate ARIA attributes.

import {
  type Signal,
  component$,
  useComputed$,
  useSignal,
  useStyles$
} from "@builder.io/qwik";
import { Checkbox } from "@kunai-consulting/qwik";
import { LuCheck } from "@qwikest/icons/lucide";

export default component$(() => {
  useStyles$(styles);

  const formData = useSignal<Record<string, FormDataEntryValue>>();
  const isChecked = useSignal(false);
  const isSubmitAttempt = useSignal(false);
  const isError = useComputed$(() => !isChecked.value && isSubmitAttempt.value);

  return (
    <form
      preventdefault:submit
      noValidate
      onSubmit$={(e) => {
        const form = e.target as HTMLFormElement;
        if (!isChecked.value) {
          isSubmitAttempt.value = true;
          return;
        }

        formData.value = Object.fromEntries(new FormData(form));
      }}
      style={{ display: "flex", flexDirection: "column", gap: "8px" }}
    >
      <TermsCheckbox isChecked={isChecked} isError={isError} />
      <button type="submit">Submit</button>
      {formData.value && <div>Submitted: {JSON.stringify(formData.value, null, 2)}</div>}
    </form>
  );
});

type TermsCheckboxProps = {
  isChecked: Signal<boolean>;
  isError: Signal<boolean>;
};

export const TermsCheckbox = component$(({ isChecked, isError }: TermsCheckboxProps) => {
  return (
    <Checkbox.Root name="terms" required bind:checked={isChecked}>
      <Checkbox.HiddenInput />
      <div
        style={{ display: "flex", alignItems: "center", gap: "8px", marginBottom: "8px" }}
      >
        <Checkbox.Trigger class="checkbox-trigger">
          <Checkbox.Indicator class="checkbox-indicator">
            <LuCheck />
          </Checkbox.Indicator>
        </Checkbox.Trigger>
        <Checkbox.Label>I accept the Terms and Conditions</Checkbox.Label>
      </div>
      {isError.value && (
        <Checkbox.ErrorMessage style={{ color: "red" }}>
          Please accept the terms and conditions
        </Checkbox.ErrorMessage>
      )}
    </Checkbox.Root>
  );
});

// example styles
import styles from "./checkbox.css?inline";

Mixed State Management

For complex selection scenarios, use the bind:checked prop to handle mixed states programmatically.

import { component$, useSignal, useStyles$ } from "@builder.io/qwik";
import { Checkbox } from "@kunai-consulting/qwik";
import { LuCheck, LuMinus } from "@qwikest/icons/lucide";

export default component$(() => {
  useStyles$(styles);

  const isChecked = useSignal<boolean | "mixed">(false);

  return (
    <>
      <Checkbox.Root bind:checked={isChecked}>
        <Checkbox.Trigger class="checkbox-trigger">
          <Checkbox.Indicator class="checkbox-indicator">
            {isChecked.value === "mixed" ? <LuMinus /> : <LuCheck />}
          </Checkbox.Indicator>
        </Checkbox.Trigger>
      </Checkbox.Root>

      <button
        type="button"
        onClick$={() => {
          isChecked.value = "mixed";
        }}
      >
        Make the checkbox mixed
      </button>
    </>
  );
});

// example styles
import styles from "./checkbox.css?inline";

The checkbox cycles through mixed → checked → unchecked states when clicked.

Component State

Using Component State

The checkbox component provides several ways to control its state:

Initial State As shown in the Initial example, you can set the initial checked state using the checked prop on Checkbox.Root:

<Checkbox.Root checked>
  <Checkbox.Trigger>
    <Checkbox.Indicator />
  </Checkbox.Trigger>
</Checkbox.Root>

Controlled State For controlled state management, use the bind:checked prop as demonstrated in the Reactive example. This allows you to bind the checkbox state to your application's state.
Indeterminate State The checkbox supports a third "mixed" or indeterminate state, as shown in the Mixed Initial example. This is useful for representing partially selected states, like in a tree structure or bulk selection interface.

State Interactions

Change Events As shown in the Change example, use the onChange$ prop to handle state changes:

<Checkbox.Root
  onChange$={(checked) => {
    // Handle the new checked state
  }}
>

Disabled State The Disabled example demonstrates how to disable the checkbox using the disabled prop. When disabled:

The checkbox cannot be interacted with
The visual state reflects the disabled status
All interactions are prevented

Programmatic Control As shown in the Programmatic example, you can programmatically control the checkbox state from outside the component:

<button
  onClick$={() => {
    // Update the bound checked state
    isChecked.value = true;
  }}
>
  Check the checkbox
</button>

Mixed State Transitions When in a mixed state, clicking the checkbox will first transition to a checked state, then follow the normal checked/unchecked cycle on subsequent clicks, as demonstrated in the Mixed Reactive example. The checkbox maintains a predictable state transition flow:

mixed → checked
checked → unchecked
unchecked → checked

Based on the examples and API documentation provided, I'll document the configuration options for the Checkbox component.

Core Configuration

Initial State

The checkbox can be configured with an initial state using the checked prop on Checkbox.Root. As shown in the initial example above, this sets an uncontrolled initial value.

The default value is false if not specified.

Value Configuration

The checkbox supports three states:

false (unchecked)
true (checked)
"mixed" (indeterminate) As shown in the mixed-initial example above, the indeterminate state can be set initially.

Form Integration

The checkbox can be configured for form submission with these props:

name - Form field name
value - Custom value for form submission (defaults to "on")
required - Makes the field required As shown in the value example above, you can customize the submitted value.

Advanced Configuration

State Management

The checkbox supports both controlled and uncontrolled state management:

// Uncontrolled
<Checkbox.Root checked={true} />
// Controlled
<Checkbox.Root bind:checked={isCheckedSignal} />

Description Configuration

When using Checkbox.Description, you must set isDescription prop on Checkbox.Root:

<Checkbox.Root isDescription>
  <Checkbox.Description>...</Checkbox.Description>
</Checkbox.Root>

Failing to set isDescription will trigger a console warning.

Technical Constraints

The bind:checked signal must be of type Signal<boolean | "mixed">
The onChange$ handler receives the new state as its only argument
When in mixed state, the first click will set the state to true These behaviors can be observed in the mixed-reactive example above.

Forms

The Checkbox component provides form integration through the <Checkbox.HiddenInput> component, which renders a native checkbox input that's visually hidden but still accessible for form submission.

import { component$, useSignal, useStyles$ } from "@builder.io/qwik";
import { Checkbox } from "@kunai-consulting/qwik";
import { LuCheck } from "@qwikest/icons/lucide";

export default component$(() => {
  useStyles$(styles);

  const formData = useSignal<Record<string, FormDataEntryValue>>();

  return (
    <form
      preventdefault:submit
      onSubmit$={(e) => {
        const form = e.target as HTMLFormElement;
        formData.value = Object.fromEntries(new FormData(form));
      }}
      style={{ display: "flex", flexDirection: "column", gap: "8px" }}
    >
      <TermsCheckbox />
      <button type="submit">Submit</button>
      {formData.value && <div>Submitted: {JSON.stringify(formData.value, null, 2)}</div>}
    </form>
  );
});

export const TermsCheckbox = component$(() => {
  return (
    <Checkbox.Root name="terms">
      <Checkbox.HiddenInput />
      <div style={{ display: "flex", alignItems: "center", gap: "8px" }}>
        <Checkbox.Trigger class="checkbox-trigger">
          <Checkbox.Indicator class="checkbox-indicator">
            <LuCheck />
          </Checkbox.Indicator>
        </Checkbox.Trigger>
        <Checkbox.Label>I accept the Terms and Conditions</Checkbox.Label>
      </div>
    </Checkbox.Root>
  );
});

// example styles
import styles from "./checkbox.css?inline";

The following props can be used to configure the form behavior:

name: Sets the name of the form field
value: Sets a custom value for the checkbox (defaults to "on")
required: Makes the checkbox a required form field

import { component$, useSignal, useStyles$ } from "@builder.io/qwik";
import { Checkbox } from "@kunai-consulting/qwik";
import { LuCheck } from "@qwikest/icons/lucide";

export default component$(() => {
  useStyles$(styles);

  const formData = useSignal<Record<string, FormDataEntryValue>>();

  return (
    <form
      preventdefault:submit
      onSubmit$={(e) => {
        const form = e.target as HTMLFormElement;
        formData.value = Object.fromEntries(new FormData(form));
      }}
      style={{ display: "flex", flexDirection: "column", gap: "8px" }}
    >
      <TermsCheckbox />
      <button type="submit">Submit</button>
      {formData.value && <div>Submitted: {JSON.stringify(formData.value, null, 2)}</div>}
    </form>
  );
});

export const TermsCheckbox = component$(() => {
  return (
    <Checkbox.Root name="terms" value="checked">
      <Checkbox.HiddenInput />
      <div style={{ display: "flex", alignItems: "center", gap: "8px" }}>
        <Checkbox.Trigger class="checkbox-trigger">
          <Checkbox.Indicator class="checkbox-indicator">
            <LuCheck />
          </Checkbox.Indicator>
        </Checkbox.Trigger>
        <Checkbox.Label>I accept the Terms and Conditions</Checkbox.Label>
      </div>
    </Checkbox.Root>
  );
});

// example styles
import styles from "./checkbox.css?inline";

Form Validation

The Checkbox supports form validation through the <Checkbox.ErrorMessage> component. When rendered, it automatically puts the checkbox in an invalid state and connects it with the error message via ARIA.

import {
  type Signal,
  component$,
  useComputed$,
  useSignal,
  useStyles$
} from "@builder.io/qwik";
import { Checkbox } from "@kunai-consulting/qwik";
import { LuCheck } from "@qwikest/icons/lucide";

export default component$(() => {
  useStyles$(styles);

  const formData = useSignal<Record<string, FormDataEntryValue>>();
  const isChecked = useSignal(false);
  const isSubmitAttempt = useSignal(false);
  const isError = useComputed$(() => !isChecked.value && isSubmitAttempt.value);

  return (
    <form
      preventdefault:submit
      noValidate
      onSubmit$={(e) => {
        const form = e.target as HTMLFormElement;
        if (!isChecked.value) {
          isSubmitAttempt.value = true;
          return;
        }

        formData.value = Object.fromEntries(new FormData(form));
      }}
      style={{ display: "flex", flexDirection: "column", gap: "8px" }}
    >
      <TermsCheckbox isChecked={isChecked} isError={isError} />
      <button type="submit">Submit</button>
      {formData.value && <div>Submitted: {JSON.stringify(formData.value, null, 2)}</div>}
    </form>
  );
});

type TermsCheckboxProps = {
  isChecked: Signal<boolean>;
  isError: Signal<boolean>;
};

export const TermsCheckbox = component$(({ isChecked, isError }: TermsCheckboxProps) => {
  return (
    <Checkbox.Root name="terms" required bind:checked={isChecked}>
      <Checkbox.HiddenInput />
      <div
        style={{ display: "flex", alignItems: "center", gap: "8px", marginBottom: "8px" }}
      >
        <Checkbox.Trigger class="checkbox-trigger">
          <Checkbox.Indicator class="checkbox-indicator">
            <LuCheck />
          </Checkbox.Indicator>
        </Checkbox.Trigger>
        <Checkbox.Label>I accept the Terms and Conditions</Checkbox.Label>
      </div>
      {isError.value && (
        <Checkbox.ErrorMessage style={{ color: "red" }}>
          Please accept the terms and conditions
        </Checkbox.ErrorMessage>
      )}
    </Checkbox.Root>
  );
});

// example styles
import styles from "./checkbox.css?inline";

The error message is displayed when form validation fails, and the checkbox trigger receives the appropriate ARIA attributes:

aria-invalid="true"
aria-describedby pointing to the error message

Mixed State in Forms

For complex form scenarios, the checkbox supports a mixed (indeterminate) state that can be used when a form field represents a partial selection.

import { type Signal, component$, useSignal, useStyles$ } from "@builder.io/qwik";
import { Checkbox } from "@kunai-consulting/qwik";
import { LuCheck } from "@qwikest/icons/lucide";

export default component$(() => {
  useStyles$(styles);

  const formData = useSignal<Record<string, FormDataEntryValue>>();

  const isChecked = useSignal<boolean | "mixed">("mixed");

  return (
    <form
      preventdefault:submit
      onSubmit$={(e) => {
        const form = e.target as HTMLFormElement;
        formData.value = Object.fromEntries(new FormData(form));
      }}
      style={{ display: "flex", flexDirection: "column", gap: "8px" }}
    >
      <TermsCheckbox isChecked={isChecked} />
      <button
        data-test-mixed
        onClick$={() => {
          isChecked.value = "mixed";
        }}
        type="button"
      >
        Make it mixed
      </button>
    </form>
  );
});

export const TermsCheckbox = component$(
  ({ isChecked }: { isChecked: Signal<boolean | "mixed"> }) => {
    return (
      <Checkbox.Root bind:checked={isChecked}>
        <Checkbox.HiddenInput />
        <div style={{ display: "flex", alignItems: "center", gap: "8px" }}>
          <Checkbox.Trigger class="checkbox-trigger">
            <Checkbox.Indicator class="checkbox-indicator">
              <LuCheck />
            </Checkbox.Indicator>
          </Checkbox.Trigger>
          <Checkbox.Label>I accept the Terms and Conditions</Checkbox.Label>
        </div>
      </Checkbox.Root>
    );
  }
);

// example styles
import styles from "./checkbox.css?inline";

The mixed state is reflected in the hidden input's indeterminate property, ensuring proper form submission behavior.

API Reference

Checkbox Root

Inherits from: <div />

Props

Prop	Type	Default
"bind:checked"	Signal<boolean \| "mixed">	-
checked	T	-
onChange$	QRL<(checked: T) => void>	-
disabled	boolean	-
isDescription	boolean	-
name	string	-
required	boolean	-
value	string	-

Data Attributes

Attribute	Description
data-disabled	Indicates whether the checkbox is disabled
data-checked	Indicates whether the checkbox is checked
data-mixed	Indicates whether the checkbox is in an indeterminate state

Checkbox Indicator

Inherits from: <span />

Data Attributes

Attribute	Description
data-hidden	Indicates whether the indicator should be hidden based on checkbox state
data-checked	Indicates whether the checkbox is in a checked state
data-mixed	Indicates whether the checkbox is in an indeterminate state

Checkbox Trigger

Inherits from: <button />

Data Attributes

Attribute	Description
data-disabled	Indicates whether the checkbox trigger is disabled

Checkbox Description

Inherits from: <div />

Checkbox Error Message

Inherits from: <div />

Checkbox Hidden Input

Inherits from: <input />

Checkbox Label

Inherits from: <label />

Accessibility

Keyboard Interactions

Key	Description
Space	When focus is on the checkbox trigger, toggles the checkbox state between checked/unchecked/mixed
Enter	When focus is on the checkbox trigger, toggles the checkbox state between checked/unchecked/mixed (default behavior prevented)
Tab	Moves focus to the checkbox trigger and follows the natural tab order