@askrjs/ui/checkbox

Checkboxtype

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`.

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

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

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

CHECKBOX_A11Y_CONTRACTtype

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

CheckboxA11yContracttype

CheckboxA11yContract: typeof CHECKBOX_A11Y_CONTRACT

Type of the Checkbox A11y Contract object.

CheckboxAsChildPropstype

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;

CheckboxInputPropstype

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;

CheckboxOwnPropstype

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;

CheckboxPropstype

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;