# @askrjs/ui/checkbox

> Published API exports for @askrjs/ui/checkbox.

Source: [https://askrjs.com/docs/reference/api/ui/checkbox](https://askrjs.com/docs/reference/api/ui/checkbox)

Status: stable. Packages: @askrjs/ui/checkbox.

**Published packages are authoritative.** Examples may lag behind a published contract. When guidance differs, verify the exports and TypeScript declarations in your installed package, then file an issue.

## Exports

This entrypoint publishes 7 exports from the declarations shipped by @askrjs/ui.

### `Checkbox`

```ts
Checkbox: { (props: CheckboxInputProps): JSX.Element; (props: CheckboxAsChildProps): JSX.Element; }
```

Headless Checkbox component

## Responsibilities
- Apply aria-checked for checkbox state signaling
- Handle indeterminate state for native and asChild hosts
- Support controlled and uncontrolled checked state
- Forward props and refs to native input or child element
- Preserve native checkbox semantics and apply checkbox behavior to asChild hosts

## Non-Responsibilities
- Form submission orchestration beyond native input props

## Invariants
- MUST NOT add role="button" (native inputs are role="checkbox")
- checked state may be controlled or uncontrolled
- indeterminate overrides checked for state signaling
- For asChild, consumer MUST provide role="checkbox"
Renders the `checkbox` part of `checkbox` with `role="checkbox"`.

Supports polymorphic rendering via `asChild`.

````tsx
Native checkbox input
```tsx
const checked = state(false);
<Checkbox checked={checked()} onPress={() => checked.set(!checked())} />
```
````

````tsx
Polymorphic rendering (asChild)
```tsx
<Checkbox asChild checked={agreed} onPress={toggleAgree}>
<div role="checkbox">I agree to terms</div>
</Checkbox>
```
````

````tsx
Indeterminate state (partial selection)
```tsx
<Checkbox checked={someChecked} indeterminate={!allChecked && someChecked} onPress={toggleAll}>
Select All
</Checkbox>
```
````

### `CHECKBOX_A11Y_CONTRACT`

```ts
CHECKBOX_A11Y_CONTRACT: { readonly ROLE: "checkbox"; readonly KEYBOARD_ACTIVATION: readonly ["Space"]; readonly CHECKED_ATTRIBUTE: "aria-checked"; readonly INDETERMINATE_VALUE: "mixed"; readonly DISABLED_ATTRIBUTES: { readonly nativeInput: { readonly disabled: true; }; readonly nonNative: { readonly "aria-disabled": "true"; readonly tabIndex: -1; }; }; readonly DATA_ATTRIBUTES: { readonly state: "data-state"; readonly disabled: "data-disabled"; }; readonly FOCUS_RULES: { readonly enabled: "tabIndex >= 0"; readonly disabled: "tabIndex = -1"; readonly visualIndicator: "required"; }; }
```

WAI-ARIA Checkbox Pattern

Specification: https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/

A checkbox is an input mechanism that allows users to select one or more items
from a set. Unlike toggle buttons, checkboxes visually represent a checked state
with aria-checked (not aria-pressed).

## Required ARIA
- aria-checked: 'true' | 'false' | 'mixed' (indicates checkbox state)
- role: 'checkbox' (when not native input)

## Keyboard Support
- Space: Activates checkbox
- Enter: Does not activate checkbox

## Focus Management
- Checkbox is focusable when not disabled
- Visual focus indicator required

## Disabled State
- aria-disabled when disabled=true (for non-native)
- disabled attribute when native input
- Removed from tab order
- Visual disabled styling (consumer responsibility)

## Indeterminate State
- `asChild`: aria-checked='mixed'
- native input: current host path omits aria-checked and keeps data-state='indeterminate'
- Typically used for "select all" checkboxes when partial selection

### `CheckboxA11yContract`

```ts
CheckboxA11yContract: typeof CHECKBOX_A11Y_CONTRACT
```

Type of the Checkbox A11y Contract object.

### `CheckboxAsChildProps`

```ts
CheckboxAsChildProps: CheckboxOwnProps & {
  asChild: true;
  children: JSXElement;
  ref?: Ref<Element>;
}
```

Props when rendering via asChild

- `asChild`: asChild: true;

- `checked`: checked?: boolean | undefined;

- `children`: children: JSXElement;

- `defaultChecked`: defaultChecked?: boolean | undefined;

- `disabled`: disabled?: boolean | undefined;

- `indeterminate`: indeterminate?: boolean | undefined;

- `name`: name?: string | undefined;

- `onCheckedChange`: onCheckedChange?: ((checked: boolean) => void) | undefined;

- `onPress`: onPress?: ((e: PressEvent) => void) | undefined;

- `ref`: ref?: Ref<Element>;

- `required`: required?: boolean | undefined;

- `value`: value?: string | undefined;

### `CheckboxInputProps`

```ts
CheckboxInputProps: Omit<JSX.IntrinsicElements['input'], 'children' | 'onClick' | 'disabled' | 'type' | 'ref' | 'checked' | 'name' | 'value' | 'required'> & CheckboxOwnProps & {
  asChild?: false;
  ref?: Ref<HTMLInputElement>;
}
```

Props when rendering as a native <input type="checkbox"> element

- `asChild`: asChild?: false | undefined;

- `checked`: checked?: boolean | undefined;

- `children`: children?: unknown;

- `defaultChecked`: defaultChecked?: boolean | undefined;

- `disabled`: disabled?: boolean | undefined;

- `indeterminate`: indeterminate?: boolean | undefined;

- `name`: name?: string | undefined;

- `onCheckedChange`: onCheckedChange?: ((checked: boolean) => void) | undefined;

- `onPress`: onPress?: ((e: PressEvent) => void) | undefined;

- `ref`: ref?: Ref<HTMLInputElement>;

- `required`: required?: boolean | undefined;

- `value`: value?: string | undefined;

### `CheckboxOwnProps`

```ts
CheckboxOwnProps: {
  children?: unknown;
  onPress?: (e: PressEvent) => void;
  checked?: boolean;
  defaultChecked?: boolean;
  onCheckedChange?: (checked: boolean) => void;
  indeterminate?: boolean;
  disabled?: boolean;
  required?: boolean;
  name?: string;
  value?: string;
}
```

Props shared by all Checkbox variants

- `checked`: checked?: boolean | undefined;

- `children`: children?: unknown;

- `defaultChecked`: defaultChecked?: boolean | undefined;

- `disabled`: disabled?: boolean | undefined;

- `indeterminate`: indeterminate?: boolean | undefined;

- `name`: name?: string | undefined;

- `onCheckedChange`: onCheckedChange?: ((checked: boolean) => void) | undefined;

- `onPress`: onPress?: ((e: PressEvent) => void) | undefined;

- `required`: required?: boolean | undefined;

- `value`: value?: string | undefined;

### `CheckboxProps`

```ts
CheckboxProps: CheckboxInputProps | CheckboxAsChildProps
```

Discriminated union of Checkbox prop types

- `asChild`: asChild?: boolean | undefined;

- `checked`: checked?: boolean | undefined;

- `children`: children?: unknown;

- `defaultChecked`: defaultChecked?: boolean | undefined;

- `disabled`: disabled?: boolean | undefined;

- `indeterminate`: indeterminate?: boolean | undefined;

- `name`: name?: string | undefined;

- `onCheckedChange`: onCheckedChange?: ((checked: boolean) => void) | undefined;

- `onPress`: onPress?: ((e: PressEvent) => void) | undefined;

- `ref`: ref?: ((value: Element | null) => void) | { current: Element | null; } | ((value: HTMLInputElement | null) => void) | { current: HTMLInputElement | null; } | null | undefined;

- `required`: required?: boolean | undefined;

- `value`: value?: string | undefined;

## Documentation navigation

[Previous](https://askrjs.com/docs/reference/api/ui/button/index.md) | [Next](https://askrjs.com/docs/reference/api/ui/input/index.md)