Checkbox

Controlled checkbox primitive. Renders a <div role="switch"> that shows a check icon when selected (or a minus icon when indeterminate).

When to use

Use Checkbox as a low-level, controlled control when you render your own label and layout — it has no built-in label element.

Labeled field: use CheckboxInput, which wraps Checkbox with a label and helper/error text.
Group of related options: use CheckboxList.
Inside a @uxf/form form: use @uxf/form/checkbox-input, which registers the field with react-hook-form. There is no @uxf/form/checkbox twin.

Usage

import { Checkbox } from "@uxf/ui/checkbox";
import { useState } from "react";

function Example() {
    const [checked, setChecked] = useState(false);
    const onChange = (value: boolean | undefined) => setChecked(value ?? false);

    return <Checkbox name="terms" onChange={onChange} value={checked} />;
}

Props

Extends FormControlProps<boolean | undefined>, which supplies the shared controlled-field props (value, onChange, name, onBlur, onFocus, isDisabled, isFocused, isReadOnly, isInvalid, isRequired).

Prop	Type	Default	Description
`value`	`boolean \| undefined`	—	Required. Checked state.
`onChange`	`(value: boolean \| undefined, event?, ...args) => void`	—	Required. Called with the toggled value when the control is clicked.
`name`	`string`	—	Required. Field name.
`size`	`CheckboxSize`	`"default"`	Size (see below).
`indeterminate`	`boolean`	`false`	Shows the minus icon instead of the check icon.
`renderContent`	`(className: string, checked: boolean \| undefined) => ReactNode`	—	Renders custom inner content in place of the default icon.
`isDisabled`	`boolean`	`false`	Non-interactive; removes pointer events.
`isReadOnly`	`boolean`	`false`	Prevents value changes and removes the control from the tab order.
`isInvalid`	`boolean`	`false`	Error state (`aria-invalid`).
`isRequired`	`boolean`	`false`	Marks the control required (`aria-required`).
`isFocused`	`boolean`	`false`	Forces the focus indicator.
`onBlur`, `onFocus`	`FocusEventHandler`	—	Focus handlers.
`id`	`string`	—	Element id.
`className`	`string`	—	Extra class names.
`style`	`CSSProperties`	—	Inline styles.

Variants & states

Sizes (from theme.ts):

Group	Values
`size`	`default`, `lg`

CheckboxSizes is an open interface, so a project can add its own sizes via module augmentation:

declare module "@uxf/ui/checkbox/theme" {
    interface CheckboxSizes {
        sm: true;
    }
}

Behavioural states are reflected via classes and driven by the props above: selected (value), indeterminate, isDisabled, isReadOnly, isInvalid, isFocused.

Requirements

Import the component stylesheet once in your global CSS:

@import url("@uxf/ui/css/checkbox.css");

Also requires the global @uxf/ui token layer, set up once per app — see @uxf/ui setup.

Default

Open in new tab

States

Open in new tab

When to use

Use Checkbox as a low-level, controlled control when you render your own label and layout — it has no built-in label element.

Labeled field: use CheckboxInput, which wraps Checkbox with a label and helper/error text.

Group of related options: use CheckboxList.

Inside a @uxf/form form: use @uxf/form/checkbox-input, which registers the field with react-hook-form. There is no @uxf/form/checkbox twin.

Usage

import { Checkbox } from "@uxf/ui/checkbox";
import { useState } from "react";

function Example() {
    const [checked, setChecked] = useState(false);
    const onChange = (value: boolean | undefined) => setChecked(value ?? false);

    return <Checkbox name="terms" onChange={onChange} value={checked} />;
}

Props

Prop

Type

Default

Description

value

boolean | undefined

—

Required. Checked state.

onChange

(value: boolean | undefined, event?, ...args) => void

—

Required. Called with the toggled value when the control is clicked.

name

string

—

Required. Field name.

size

CheckboxSize

"default"

Size (see below).

indeterminate

boolean

false

Shows the minus icon instead of the check icon.

renderContent

(className: string, checked: boolean | undefined) => ReactNode

—

Renders custom inner content in place of the default icon.

isDisabled

boolean

false

Non-interactive; removes pointer events.

isReadOnly

boolean

false

Prevents value changes and removes the control from the tab order.

isInvalid

boolean

false

Error state (aria-invalid).

isRequired

boolean

false

Marks the control required (aria-required).

isFocused

boolean

false

Forces the focus indicator.

onBlur, onFocus

FocusEventHandler

—

Focus handlers.

id

string

—

Element id.

className

string

—

Extra class names.

style

CSSProperties

—

Inline styles.

Variants & states

Sizes (from theme.ts):

Group

Values

size

default, lg

CheckboxSizes is an open interface, so a project can add its own sizes via module augmentation:

declare module "@uxf/ui/checkbox/theme" {
    interface CheckboxSizes {
        sm: true;
    }
}

Behavioural states are reflected via classes and driven by the props above: selected (value), indeterminate, isDisabled, isReadOnly, isInvalid, isFocused.