Fields & selection

Checkbox

A controlled native checkbox for one independent boolean choice.

CheckboxCheckboxProps

Component workbench

Configure the production component, inspect it at responsive widths, copy synchronized JSX, and share the exact state from one workspace.

I agree

Generated example

This JSX stays synchronized with the controls and uses only public package APIs.

tsx

'use client';

import { useState } from 'react';
import { Checkbox } from '@ai-created/ui';

export function Example() {
  const [checked, setChecked] = useState(false);

  return (
    <Checkbox
      checked={checked}
      onChange={setChecked}
      label={"I agree"}
    />
  );
}

Import

tsx

import { Checkbox } from '@ai-created/ui';

Install from a reviewed release

Replace the version placeholder with the release tag your product has reviewed.

shell

npm install --install-links "git+https://github.com/TheMarco/ai-created-ui.git#vX.Y.Z"

Load semantic tokens

css

@import '@ai-created/ui/styles/tokens.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

Extend Tailwind

module.exports = {
  presets: [require('@ai-created/ui/tailwind-preset')],
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@ai-created/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
};

Anatomy

Named regions define what belongs to the component, what remains optional, and where semantic responsibility lives.

Label wrapper

Required

Full clickable label and layout root.

label

Native input

Required

Visually hidden checkbox owning state and semantics.

input[type=checkbox]

Visual box

Required

20px state indicator and focus target proxy.

Check icon

Optional

Decorative selected mark.

Label text

Required

Visible accessible name.

Construction and authoring

The Figma-equivalent asset model, auto-layout, resizing, properties, slots, content bounds, localization, and governance contract.

Asset kind

component

Design library name

Components/Forms/Checkbox

Maturity

stable

Last reviewed

2026-08-29

Canvas applicability

Publish checked, unchecked, disabled, hover, and focus states with a text property.

Auto layout

Direction: horizontal
Gap: 12.5px
Padding: 0px
Alignment: Center vertically
Wrap: Label wraps

Measurements use the 20px playground and Figma reference root. The package does not set html font-size. Rem-based dimensions scale with the consumer root; literal px dimensions remain fixed.

Resizing

Width: fill
Height: hug
Minimum width: 44px interaction area recommended
Maximum width: Parent controlled
Minimum height: 44px target recommended
Maximum height: Content controlled
Overflow: visible

Exposed design properties

Property	Type	Default	Code mapping	Options or notes
CheckedRequired	variant	false	checked boolean	false, true
State preview	variant	default	Native hover/focus-visible and disabled boolean	default, hover, focus-visible, disabled
LabelRequired	text	I agree	label	No additional constraint

Nested assets and slots

Native input

primitive / required

Visually hidden checkbox that owns semantics.

<input type="checkbox">

Indicator

subcomponent / required

20px visual check surface.

Internal visual span

Label

slot / required

Visible choice label.

label

Content limits

Label

One sentence, recommended maximum two lines

Overflow: Wrap naturally; do not truncate.

The consequence of the choice must remain explicit.

Localization and RTL

Translatable: Label

Indicator sits on the logical start side.
Checkmark does not mirror.
Test two-line labels.
Test 200% text size and a 44px minimum target.

Responsive behavior

Fill the parent width with a content-height label.

No internal breakpoint

Label wraps while the indicator remains vertically centered, matching items-center.
The Figma label fills the remaining width and the instance hugs its height; the default authoring width is 320px.
Parent controls list spacing.

Authoring limits

Prototype checked state does not validate native input behavior.
Component is controlled; the consumer must update checked in onChange.

Accountable owner

Design systems form foundations owner

Canonical source: src/components/Checkbox.tsx

State or target-size changes require input accessibility review.
A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.
The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change.

Read the system construction standard

Visual specification

These measurements and semantic tokens define the supported visual contract. Local overrides should preserve the same hierarchy and interaction cues.

Indicator

20 × 20px

Indicator radius

4px

Content gap

12.5px

Check icon

15 × 15px, 3px SVG stroke at its 24px viewBox

Label text

15px

Rules

The whole label is clickable.
Keep label adjacent to the indicator.
Use checkbox only for choices that can stand independently.
Measurements use the 20px playground and Figma reference root. The package does not set html font-size. Rem-based dimensions scale with the consumer root; literal px dimensions remain fixed.

Token dependencies

--color-action-primary

Checked fill and border.

--color-on-action

Checked mark.

--color-control-border / --color-control-border-strong

Unchecked and hover boundary.

--color-focus

Peer focus-visible outline.

--color-text2

Label.

--motion-fast

State transition.

States and behavior

A component is not complete until its passive, interactive, disabled, and exceptional states remain understandable in both themes.

checked

Trigger: checked is true.
Visual response: Solid action fill with white check.
Behavior: Activation requests false through onChange.
Accessibility: Native checked state is exposed.

unchecked

Trigger: checked is false.
Visual response: Transparent box with standard control border at rest; strong on enabled hover.
Behavior: Activation requests true through onChange.

disabled

Trigger: disabled is true.
Visual response: Indicator and label use 50% opacity; cursor is not-allowed.
Behavior: Native input cannot focus or change.

focus-visible

Trigger: Keyboard focus reaches the hidden input.
Visual response: Visual box receives 2px outline with 3px offset.
Behavior: Space toggles the input.

Accessibility contract

Semantics, accessible naming, keyboard behavior, focus and announcements are implementation requirements, not optional documentation.

Semantics: Native checkbox nested in an associated label.
Accessible name: Required visible label string supplies the name.

State is controlled; update checked in onChange.
Do not hide or replace the visible label with color/icon only.
Use disabled for unavailable choices.

Keyboard behavior

Space: Toggles the focused checkbox.
Tab / Shift+Tab: Moves focus to or from an enabled checkbox.

Implementation

Use the public package API and preserve the controlled-state, native-attribute, and ref contracts described below.

tsx

import { Checkbox } from '@ai-created/ui';

Server Component compatible

A generated id connects the label and input.
The component forwards the HTMLInputElement ref.
onChange receives the next boolean value rather than a DOM event.

tsx

<Checkbox checked={accepted} onChange={setAccepted} label="I agree" />

Public API

These props and helpers are compatibility contracts. Changes require migration guidance and release notes.

Prop	Type	Default	Contract
checked	boolean	required	Controlled checked state.
onChange	(checked: boolean) => void	required	Called when the value changes.
label	string	required	Visible accessible label.
disabled	boolean	false	Disables the native input.
className	string	undefined	Additional classes.

Usage guidance

These rules keep the component recognizable across products without preventing deliberate composition.

Do

Use affirmative labels that make sense when checked.
Group related checkboxes under a visible group heading.

Do not

Do not use for mutually exclusive options.
Do not require users to infer the unchecked meaning from a negative label.

Testing contract

The component should be verified as rendered UI, an interaction model, an accessibility surface, and a theme-aware visual artifact.

Unit

Reflects controlled checked and disabled props.
Calls onChange once with the next value.

Interaction

Label click and Space toggle; disabled state does not.

Accessibility

Native checkbox has visible associated label and focus indicator.

Visual

Capture checked/unchecked, hover, focus, disabled, long label, and both themes.

Related specifications

radio-group toggle field