CheckboxList

Controlled group of checkboxes backed by an array value. Renders a labeled form wrapper containing one CheckboxInput per option; the value is the list of selected option ids.

When to use

Use @uxf/ui/checkbox-list to let the user pick multiple options from a fixed list, tracking the selection as an array of ids.

Inside a @uxf/form form: use @uxf/form/checkbox-list instead — it registers the field with react-hook-form. Reach for the ui component for a standalone, controlled list.
A single boolean: use CheckboxInput.

Usage

import { CheckboxList } from "@uxf/ui/checkbox-list";
import { useState } from "react";

const OPTIONS = [
    { id: "1", label: "Option 1" },
    { id: "2", label: "Option 2" },
    { id: "3", label: "Option 3" },
];

function Example() {
    const [values, setValues] = useState<string[] | null>([]);

    return (
        <CheckboxList
            label="Pick options"
            name="options"
            onChange={setValues}
            options={OPTIONS}
            value={values}
        />
    );
}

Props

CheckboxList is generic over the option id type: CheckboxList<ValueId extends string | number, Option>. ValueId is inferred from options. Props extend FormControlProps<ValueId[] | null>.

Prop	Type	Default	Description
`value`	`ValueId[] \| null`	—	Required. Ids of the currently selected options.
`onChange`	`(value: ValueId[] \| null, event?, ...args) => void`	—	Required. Called with the next selection when an option is toggled.
`name`	`string`	—	Required. Field name (shared by all options).
`options`	`Option[]`	—	Required. Options to render (see below).
`label`	`ReactNode`	—	Required. Group label.
`helperText`	`ReactNode`	—	Helper/error text for the group.
`hasHiddenLabel`	`boolean`	`false`	Visually hides the group label (kept for screen readers).
`isDisabled`	`boolean`	`false`	Disables the whole group.
`isReadOnly`	`boolean`	`false`	Read-only state for the group.
`isInvalid`	`boolean`	`false`	Error state.
`isRequired`	`boolean`	`false`	Marks the group required.
`id`	`string`	—	Base id (an id is generated with `useId` when omitted).
`className`	`string`	—	Extra class names on the wrapper.

onBlur and onFocus (inherited from FormControlProps) are forwarded to each option.

CheckboxListOption

Field	Type	Description
`id`	`ValueId` (`number \| string`)	Required. Unique option id, stored in `value`.
`label`	`ReactNode`	Required. Option label.
`isDisabled`	`boolean`	Disables just this option (also disabled when the whole group is).

Exported types: CheckboxListProps, CheckboxListOption, CheckboxListValueId (= number | string).

Note: the group label uses hasHiddenLabel, not hiddenLabel as on CheckboxInput.

Variants & states

Reflected via classes on the wrapper: isDisabled, isReadOnly, isInvalid, isRequired.

Requirements

Import the component stylesheet once in your global CSS. It renders CheckboxInput (which in turn renders Checkbox), so those stylesheets are required too:

@import url("@uxf/ui/css/checkbox-list.css");
@import url("@uxf/ui/css/checkbox-input.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

When to use

Use @uxf/ui/checkbox-list to let the user pick multiple options from a fixed list, tracking the selection as an array of ids.

Inside a @uxf/form form: use @uxf/form/checkbox-list instead — it registers the field with react-hook-form. Reach for the ui component for a standalone, controlled list.

A single boolean: use CheckboxInput.

Usage

import { CheckboxList } from "@uxf/ui/checkbox-list"; import { useState } from "react"; const OPTIONS = [ { id: "1", label: "Option 1" }, { id: "2", label: "Option 2" }, { id: "3", label: "Option 3" }, ]; function Example() { const [values, setValues] = useState<string[] | null>([]); return ( <CheckboxList label="Pick options" name="options" onChange={setValues} options={OPTIONS} value={values} /> ); }

Props

CheckboxList is generic over the option id type: CheckboxList<ValueId extends string | number, Option>. ValueId is inferred from options. Props extend FormControlProps<ValueId[] | null>.

Prop

Type

Default

Description

value

ValueId[] | null

—

Required. Ids of the currently selected options.

onChange

(value: ValueId[] | null, event?, ...args) => void

—

Required. Called with the next selection when an option is toggled.

name

string

—

Required. Field name (shared by all options).

options

Option[]

—

Required. Options to render (see below).

label

ReactNode

—

Required. Group label.

helperText

ReactNode

—

Helper/error text for the group.

hasHiddenLabel

boolean

false

Visually hides the group label (kept for screen readers).

isDisabled

boolean

false

Disables the whole group.

isReadOnly

boolean

false

Read-only state for the group.

isInvalid

boolean

false

Error state.

isRequired

boolean

false

Marks the group required.

id

string

—

Base id (an id is generated with useId when omitted).

className

string

—

Extra class names on the wrapper.

onBlur and onFocus (inherited from FormControlProps) are forwarded to each option.

CheckboxListOption

Field

Type

Description

id

ValueId (number | string)

Required. Unique option id, stored in value.

label

ReactNode

Required. Option label.

isDisabled

boolean

Disables just this option (also disabled when the whole group is).

Exported types: CheckboxListProps, CheckboxListOption, CheckboxListValueId (= number | string).

Note: the group label uses hasHiddenLabel, not hiddenLabel as on CheckboxInput.

Requirements

Import the component stylesheet once in your global CSS. It renders CheckboxInput (which in turn renders Checkbox), so those stylesheets are required too:

@import url("@uxf/ui/css/checkbox-list.css"); @import url("@uxf/ui/css/checkbox-input.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.