mirror of
https://github.com/nextui-org/nextui.git
synced 2025-12-08 19:26:11 +00:00
f0008d070a
* chore(input): set validationBehavior to native * chore(docs): revise validate content in input * chore(input): set validationBehavior to native * chore(docs): add Validation Behavior to breaking change * chore(docs): revise content in cli * chore(docs): fix typo * chore(docs): update validate in other components * chore(docs): update validate content * chore(input): undo validationBehavior * refactor(docs): revise validate content
125 lines
9.1 KiB
Plaintext
125 lines
9.1 KiB
Plaintext
---
|
||
title: "Checkbox Group"
|
||
description: "A CheckboxGroup allows users to select one or more items from a list of choices."
|
||
---
|
||
|
||
import {checkboxGroupContent} from "@/content/components/checkbox-group";
|
||
|
||
# Checkbox Group
|
||
|
||
A CheckboxGroup allows users to select one or more items from a list of choices.
|
||
|
||
<ComponentLinks component="checkbox" storybook="checkboxgroup" reactAriaHook="useCheckboxGroup" />
|
||
|
||
---
|
||
|
||
|
||
|
||
## Installation
|
||
|
||
<PackageManagers
|
||
showGlobalInstallWarning
|
||
commands={{
|
||
cli: "npx nextui-cli@latest add checkbox",
|
||
npm: "npm install @nextui-org/checkbox",
|
||
yarn: "yarn add @nextui-org/checkbox",
|
||
pnpm: "pnpm add @nextui-org/checkbox",
|
||
bun: "bun add @nextui-org/checkbox"
|
||
}}
|
||
/>
|
||
|
||
|
||
## Import
|
||
|
||
NextUI exports 2 checkbox-related components:
|
||
|
||
- **CheckboxGroup**: The root component, it wraps the label and the wrapper.
|
||
- **Checkbox**: The checkbox component.
|
||
|
||
<ImportTabs
|
||
commands={{
|
||
main: 'import {CheckboxGroup, Checkbox} from "@nextui-org/react";',
|
||
individual: 'import {CheckboxGroup, Checkbox} from "@nextui-org/checkbox";',
|
||
}}
|
||
/>
|
||
|
||
## Usage
|
||
|
||
<CodeDemo title="Usage" files={checkboxGroupContent.usage} />
|
||
|
||
### Disabled
|
||
|
||
<CodeDemo title="Disabled" files={checkboxGroupContent.disabled} />
|
||
|
||
### Horizontal
|
||
|
||
<CodeDemo title="Horizontal" files={checkboxGroupContent.horizontal} />
|
||
|
||
### Controlled
|
||
|
||
You can use the `value` and `onValueChange` properties to control the checkbox input value.
|
||
|
||
<CodeDemo title="Controlled" files={checkboxGroupContent.controlled} />
|
||
|
||
### Invalid
|
||
|
||
<CodeDemo title="Invalid" files={checkboxGroupContent.invalid} />
|
||
|
||
## Slots
|
||
|
||
- **base**: Checkbox group root wrapper, it wraps the label and the wrapper.
|
||
- **wrapper**: Checkbox group wrapper, it wraps all checkboxes.
|
||
- **label**: Checkbox group label, it is placed before the wrapper.
|
||
- **description**: The description of the checkbox group.
|
||
- **errorMessage**: The error message of the checkbox group.
|
||
|
||
### Custom Styles
|
||
|
||
You can customize the `CheckboxGroup` component by passing custom Tailwind CSS classes to the component slots.
|
||
|
||
<CodeDemo title="Custom Styles" files={checkboxGroupContent.customStyles} />
|
||
|
||
### Custom Implementation
|
||
|
||
In case you need to customize the checkbox even further, you can use the `useCheckboxGroup` hook to create your own implementation.
|
||
|
||
<CodeDemo title="Custom Implementation" files={checkboxGroupContent.customImplementation} />
|
||
|
||
> **Note**: We used [Tailwind Variants](https://www.tailwind-variants.org/) to implement the styles above, you can use any other library such as [clsx](https://www.npmjs.com/package/clsx) to achieve the same result.
|
||
|
||
<Spacer y={4} />
|
||
|
||
## API
|
||
|
||
### Checkbox Group Props
|
||
|
||
| Attribute | Type | Description | Default |
|
||
| ------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
|
||
| children | `ReactNode[]` \| `ReactNode[]` | The checkboxes items. | - |
|
||
| orientation | `vertical` \| `horizontal` | The axis the checkbox group items should align with. | `vertical` |
|
||
| color | `default` \| `primary` \| `secondary` \| `success` \| `warning` \| `danger` | The color of the checkboxes. | `primary` |
|
||
| size | `xs` \| `sm` \| `md` \| `lg` \| `xl` | The size of the checkboxes. | `md` |
|
||
| radius | `none` \| `base` \| `xs` \| `sm` \| `md` \| `lg` \| `xl` \| `full` | The radius of the checkboxes. | `md` |
|
||
| name | `string` | The name of the CheckboxGroup, used when submitting an HTML form. | - |
|
||
| label | `string` | The label of the CheckboxGroup. | - |
|
||
| value | `string[]` | The current selected values. (controlled). | - |
|
||
| lineThrough | `boolean` | Whether the checkboxes label should be crossed out. | `false` |
|
||
| defaultValue | `string[]` | The default selected values. (uncontrolled). | - |
|
||
| isInvalid | `boolean` | Whether the checkbox group is invalid. | `false` |
|
||
| validationState | `valid` \| `invalid` | Whether the inputs should display its "valid" or "invalid" visual styling. (**Deprecated**) use **isInvalid** instead. | - |
|
||
| description | `ReactNode` | The checkbox group description. | - |
|
||
| errorMessage | `ReactNode` \| `((v: ValidationResult) => ReactNode)` | The checkbox group error message. | - |
|
||
| validate | `(value: string[]) => ValidationError ｜ true ｜ null ｜ undefined` | Validate input values when committing (e.g. on blur), returning error messages for invalid values. Validation errors are displayed upon form submission if `validationBehavior` is set to `native`. For real-time validation, use the `isInvalid` prop.| - |
|
||
| validationBehavior | `native` \| `aria` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.| `aria` |
|
||
| isDisabled | `boolean` | Whether the checkbox group is disabled. | `false` |
|
||
| isRequired | `boolean` | Whether user checkboxes are required on the input before form submission. | `false` |
|
||
| isReadOnly | `boolean` | Whether the checkboxes can be selected but not changed by the user. | - |
|
||
| disableAnimation | `boolean` | Whether the animation should be disabled. | `false` |
|
||
| classNames | `Record<"base"｜ "wrapper"｜ "label", string>` | Allows to set custom class names for the checkbox group slots. | - |
|
||
|
||
### Checkbox Group Events
|
||
|
||
| Attribute | Type | Description |
|
||
| --------- | --------------------------- | ---------------------------------------------- |
|
||
| onChange | `(value: string[]) => void` | Handler that is called when the value changes. |
|