Checkbox Component

A flexible checkbox component supporting both single toggles and multi-select groups. Features group keyboard navigation, custom rendering, comprehensive styling options, and accessible defaults.

Overview

Checkbox works in two modes: group for multi-select lists and single for simple yes/no toggles. It supports custom icons, disabled states, read-only behavior, error messages, unrestricted styling, and native Tab/Space keyboard support in group mode (checkboxes are independently focusable and are not arrow-navigable, unlike radio groups).

Import Component From Library

tsx

1import { Checkbox } from "@neuctra/ui";

Single Usage Code

Use the default single mode for one boolean value. Pass checked and onCheckedChange to control the checkbox.

tsx

1import { useState } from 'react';
2import { Checkbox } from '@neuctra/ui';
3
4function SingleCheckboxExample() {
5  const [checked, setChecked] = useState(false);
6
7  return (
8    <Checkbox
9      label="Subscribe to newsletter"
10      checked={checked}
11      onCheckedChange={setChecked}
12    />
13  );
14}

Group Usage Code

Use mode="group" for multiple checkbox options. Control selections with selectedValues and onChange.

tsx

1import { useState } from 'react';
2import { Checkbox } from '@neuctra/ui';
3
4function CheckboxGroupExample() {
5  const [selectedValues, setSelectedValues] = useState(['react']);
6
7  const options = [
8    { label: 'React', value: 'react' },
9    { label: 'Vue', value: 'vue' },
10    { label: 'Angular', value: 'angular' },
11  ];
12
13  return (
14    <Checkbox
15      mode="group"
16      options={options}
17      selectedValues={selectedValues}
18      onChange={setSelectedValues}
19    />
20  );
21}

Single Mode

Use mode="single" for a simple on/off checkbox. Track state with checked and onCheckedChange.

I agree to the terms

Group Mode

Use mode="group" to display a list of checkboxes with multi-select behavior. Pass options, then track selections with selectedValues and onChange.

ReactVueAngular

Disabled & Error States

Disable the entire group or individual options, and show error messages below the component.

EnabledDisabled

At least one option is required

Custom Rendering

Use renderItem to completely customize each checkbox entry. Useful for building card grids, complex UIs, or branded checkboxes.

tsx

1<Checkbox
2  mode="group"
3  options={[
4    { label: "Option A", value: "a" },
5    { label: "Option B", value: "b" },
6  ]}
7  selectedValues={values}
8  onChange={setValues}
9  renderItem={({ option, checked, toggle }) => (
10    <div
11      onClick={toggle}
12      className={`p-3 border rounded cursor-pointer transition ${
13        checked ? "bg-blue-50 border-blue-500" : "bg-white border-gray-300"
14      }`}
15    >
16      <div className="font-medium">{option.label}</div>
17      <div className="text-sm text-gray-600">Details about {option.label}</div>
18    </div>
19  )}
20/>

Styling & Customization

Complete control over appearance via Tailwind classes, inline styles, and custom icons.

Styling Layers

className / containerClassName — wrapper styles
itemClassName / labelClassName — per-item wrapper
textClassName — label text styling
iconClassName / iconSize — checkbox icon
errorClassName — error message styling

tsx

1<Checkbox
2  mode="group"
3  options={options}
4  selectedValues={values}
5  onChange={setValues}
6  className="space-y-3 p-4"
7  itemClassName="hover:bg-gray-50 px-2 py-1 rounded"
8  textClassName="text-blue-600 font-semibold"
9  iconSize={24}
10  iconClassName="bg-blue-100 border-blue-500"
11/>

Props Table

Prop	Type	Default	Description
mode	"single" \| "group"	"single"	Single toggle or multi-select list.
label	string	—	Label text in single mode.
checked	boolean	false	Checked state in single mode.
onCheckedChange	(checked: boolean) => void	—	Called when toggled in single mode.
options	Option[]	[]	List of options with label, value, disabled.
selectedValues	string[]	[]	Currently selected values.
onChange	(values: string[]) => void	—	Called when selection changes.
name	string	—	HTML name attribute for form submission.
disabled	boolean	false	Disables all checkboxes.
readOnly	boolean	false	Prevents selection changes (display only).
required	boolean	false	Marks inputs as required for validation.
error	string	—	Error message displayed below the group.
className	string	—	Wrapper container classes.
containerClassName	string	—	Override wrapper classes.
itemClassName	string	—	Classes for each checkbox item.
labelClassName	string	—	Classes for label wrapper.
textClassName	string	—	Classes for label text.
iconClassName	string	—	Classes for checkbox icon/box.
checkClassName	string	—	Styles the checkmark SVG inside the checkbox.
errorClassName	string	—	Classes for error message.
style	CSSProperties	—	Inline styles for wrapper.
containerStyle	CSSProperties	—	Inline styles for container.
itemStyle	CSSProperties	—	Inline styles for items.
labelStyle	CSSProperties	—	Inline styles for labels.
textStyle	CSSProperties	—	Inline styles for text.
iconStyle	CSSProperties	—	Inline styles for icon.
errorStyle	CSSProperties	—	Inline styles for error text.
customIcon	(checked, option?) => ReactNode	—	Custom checkbox icon renderer.
iconSize	number	20	Icon size in pixels.
renderItem	({ option, checked, focused, toggle }) => ReactNode	—	Fully customize each checkbox item.

Common Mistakes

selectedValues="react"

Must be an array. Use ["react"] instead.

mode="single" + selectedValues

Use checked and onCheckedChange in single mode.

selectedValues={['react', 'vue']}

Correct: array of values.

mode="single" checked={true} onCheckedChange={...}

Use correct props for single mode.

Pro Tips

Use mode="group" when handling multiple selections and mode="single" for boolean toggles like settings.
Prefer selectedValues as the single source of truth — avoid mixing internal and external state.
Use customIcon to fully match your design system (checkbox, toggle, or animated indicators).
Use renderItem when you need fully custom layouts like cards, settings rows, or list items.
Keep readOnly for UI display-only states instead of disabling interactions completely.
Combine itemClassName + textClassName for clean separation between layout and typography styling.
Avoid managing checked state manually inside each item — always lift state up to the parent via onChange.
Each checkbox is independently focusable — use Tab to move between options and Space to toggle. Unlike RadioGroup, Checkbox groups are not arrow-key navigable.

Frequently Asked Questions

How do I install and import the Checkbox component?

Install the @neuctra/ui package, then import it with: import { Checkbox } from "@neuctra/ui";

Can I customize the Checkbox component's appearance?

Yes. Checkbox accepts a className prop for custom Tailwind CSS classes, so you can adjust spacing, layout, and styling without overriding the component internals.

Is the Checkbox component accessible?

Checkbox is built with semantic HTML and standard ARIA attributes, and supports keyboard navigation and focus states out of the box, so it works well with screen readers and keyboard-only users.