# Checkbox Group Field

A labeled fieldset of checkbox options with description and helper or error text.

## Installation

```tsx
import {
  CheckboxGroupField,
  CheckboxGroupFieldOption,
} from "@makeplane/propel/components/checkbox-group-field";
```
## Usage

```tsx
import {
  CheckboxGroupField,
  CheckboxGroupFieldOption,
} from "@makeplane/propel/components/checkbox-group-field";

export default function BasicDemo() {
  return (
    <CheckboxGroupField
      name="notifications"
      label="Notifications"
      description="Choose every update channel you want."
      density="comfortable"
      size="lg"
      defaultValue={["email"]}
      hint="At least one channel is recommended."
    >
      <CheckboxGroupFieldOption value="email" label="Email" />
      <CheckboxGroupFieldOption value="slack" label="Slack" description="Workspace alerts." />
    </CheckboxGroupField>
  );
}
```
## Examples

### Sizes

The legend, description, and option text scale together across `lg`, `xl`, and `2xl`.

```tsx
import {
  CheckboxGroupField,
  CheckboxGroupFieldOption,
} from "@makeplane/propel/components/checkbox-group-field";

export default function SizesDemo() {
  return (
    <div className="flex flex-wrap items-start gap-10">
      {(["lg", "xl", "2xl"] as const).map((size) => (
        <CheckboxGroupField
          key={size}
          name={`notifications-${size}`}
          label={size}
          description="Choose every update channel you want."
          density="comfortable"
          size={size}
          defaultValue={["email"]}
        >
          <CheckboxGroupFieldOption value="email" label="Email" />
          <CheckboxGroupFieldOption value="slack" label="Slack" description="Workspace alerts." />
        </CheckboxGroupField>
      ))}
    </div>
  );
}
```

### Densities

`density` controls the spacing between option rows: `comfortable` keeps a gap, `compact` stacks them flush.

```tsx
import {
  CheckboxGroupField,
  CheckboxGroupFieldOption,
} from "@makeplane/propel/components/checkbox-group-field";

export default function DensitiesDemo() {
  return (
    <div className="flex flex-wrap items-start gap-10">
      <CheckboxGroupField
        name="notifications-comfortable"
        label="comfortable"
        description="Choose every update channel you want."
        density="comfortable"
        size="lg"
        defaultValue={["email"]}
      >
        <CheckboxGroupFieldOption value="email" label="Email" />
        <CheckboxGroupFieldOption value="slack" label="Slack" description="Workspace alerts." />
      </CheckboxGroupField>
      <CheckboxGroupField
        name="notifications-compact"
        label="compact"
        description="Choose every update channel you want."
        density="compact"
        size="lg"
        defaultValue={["email"]}
      >
        <CheckboxGroupFieldOption value="email" label="Email" />
        <CheckboxGroupFieldOption value="slack" label="Slack" description="Workspace alerts." />
      </CheckboxGroupField>
    </div>
  );
}
```

### Invalid

Setting `error` marks the whole group invalid and recolors every unchecked option's border to `danger`.

```tsx
import {
  CheckboxGroupField,
  CheckboxGroupFieldOption,
} from "@makeplane/propel/components/checkbox-group-field";

export default function InvalidDemo() {
  return (
    <CheckboxGroupField
      name="notifications"
      label="Notifications"
      description="Choose every update channel you want."
      density="comfortable"
      size="lg"
      error="Choose at least one channel."
    >
      <CheckboxGroupFieldOption value="email" label="Email" />
      <CheckboxGroupFieldOption value="slack" label="Slack" description="Workspace alerts." />
    </CheckboxGroupField>
  );
}
```
## API Reference

### CheckboxGroupField

Ready-to-use checkbox group field with legend, description, and helper/error text.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` | — | Checkbox option rows, usually `CheckboxGroupFieldOption`. |
| `density` (required) | `"comfortable" \| "compact"` | — | Spacing between checkbox options. |
| `label` (required) | `string` | — | Visible fieldset legend. |
| `size` (required) | `"md" \| "lg" \| "xl" \| "2xl"` | — | Legend and helper text size. |
| `name` (required) | `string` | — | Submitted field name. |
| `render` | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, CheckboxGroupState>` | — | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| `description` | `ReactNode` | — | Supporting text shown below the legend. |
| `error` | `ReactNode` | — | Error text shown below the group. |
| `hint` | `ReactNode` | — | Helper text shown below the group. Replaced by `error` when an error is set. |

### CheckboxGroupFieldOption

A checkbox option row for use inside `CheckboxGroupField` or a custom `CheckboxGroup`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | — | Visible option label. |
| `stretch` | `"auto" \| "full"` | `"auto"` | Width of the clickable label row when `label` is present. Ready-made concern — the elements `CheckboxLabel` requires `stretch` explicitly. |
| `description` | `ReactNode` | — | Optional supporting text announced as the checkbox description. |
| `size` | `"md" \| "lg" \| "xl" \| "2xl"` | — | Label and description size. Inherited from `CheckboxGroupField` when omitted. |