Checkbox Group

The CheckboxGroup allows users to select one or more items from a list of choices.

A checkbox group

Option 1

Option 2

Option 3

Option 4

---

Usage

import { CheckboxGroup } from "@newfold/ui-component-library";

const options = [
    { label: 'Option 1', value: '1' },
    { label: 'Option 2', value: '2' },
    { label: 'Option 3', value: '3' },
    { label: 'Option 4', value: '4' }
];

<CheckboxGroup
    id="checkbox-group"
    label="A checkbox group"
    onChange={handleChange}
    options={options}
    values={['1', '3']}
/>

---

Options

You can pass options to the CheckboxGroup component in two ways. You can pass them as an array of objects to the options prop, or you can pass them as children to the component.

1. Options as Array

Use the options prop to pass an array of options to the component. Each option must be an object with a string label and a string value property.

<CheckboxGroup 
    id="checkbox-group-array"
    label="A checkbox group"
    onChange={handleChange}
    options={[
        { label: 'Option 1', value: '1' },
        { label: 'Option 2', value: '2' },
        { label: 'Option 3', value: '3' },
        { label: 'Option 4', value: '4' }
    ]}
    values={['1', '3']}
/>

info

If you want to have pre-selected options, you must pass an array to the values prop with the values of the options you wish to be selected.

2. Options as Children

You can pass options as children to the component. Each child must be an instance of CheckboxGroup.Checkbox sub-component.

<CheckboxGroup 
    id="checkbox-group-children"
    label="A checkbox group"
    name="checkbox-group-children"
    onChange={handleChange}
>
    <CheckboxGroup.Checkbox
        checked
        id="checkbox-group-option-1"
        label="Option 1"
        name="checkbox-group-children"
        value="1"
    />
    <CheckboxGroup.Checkbox
        id="checkbox-group-option-2"
        label="Option 2"
        name="checkbox-group-children"
        value="2"
    />
    <CheckboxGroup.Checkbox
        id="checkbox-group-option-3"
        label="Option 3"
        name="checkbox-group-children"
        value="3"
    />
    <CheckboxGroup.Checkbox
        id="checkbox-group-option-4"
        label="Option 4"
        name="checkbox-group-children"
        value="4"
    />
</CheckboxGroup>

info

This method is uncontrolled. So you have to manage the state of each checkbox individually. And since the CheckboxGroup.Checkbox sub-component is mostly a wrapper around the native input[type="checkbox"] element, you can use the checked attribute as a prop to do that.

---

Label

Use the label prop to add a label to the CheckboxGroup component.

This is a label

Option 1

Option 2

Option 3

Option 4

<CheckboxGroup
    id="checkbox-group-label"
    onChange={handleChange}
    options={options}
    values={selectedValues}
    label="This is a label"
/>

---

Description

Use the description prop to add a description to the CheckboxGroup component.

A checkbox group

This is a description for the checkbox group

Option 1

Option 2

Option 3

Option 4

<CheckboxGroup
    id="checkbox-group-description"
    onChange={handleChange}
    options={options}
    values={selectedValues}
    label="This is a label"
    description="This is a description for the checkbox group"
/>

---

Disabled

Use the disabled prop to disable the CheckboxGroup component.

Disabled checkbox group

Option 1

Option 2

Option 3

Option 4

<CheckboxGroup
    id="checkbox-group-disabled"
    label="Disabled checkbox group"
    onChange={handleChange}
    options={options}
    values={selectedValues}
    disabled
/>

---

Props

Attribute	Type	Description	Default
id	string |	The id of the checkbox group.	-
name	string |	-	-
values	array |	The values of the selected checkboxes.	-
options	array |	The options for the checkbox group.	-
children	node |	You can use `CheckboxGroup.Checkbox` sub-components as children instead of passing `options`.	-
label	string |	The label for the checkbox group.	-
description	string |	The description for the checkbox group.	-
onChange	function |	The function to call when the checkbox group changes. The function will receive the new values (array) as an argument.	-
disabled	bool |	Whether the checkbox group is disabled.	-
className	string |	-	-