# Checkbox Field

A single checkbox laid out as a field row with label, description, and hint or error text.

## Installation

```tsx
import { CheckboxField } from "@makeplane/propel/components/checkbox-field";
```
## Usage

```tsx
import { CheckboxField } from "@makeplane/propel/components/checkbox-field";

export default function BasicDemo() {
  return (
    <CheckboxField
      name="emailUpdates"
      value="enabled"
      label="Email updates"
      size="lg"
      description="Send a message when the deployment status changes."
      hint="You can change this later."
      defaultChecked
    />
  );
}
```
## Examples

### Sizes

`size` scales the label, description, and helper text; the checkbox box keeps one size.

```tsx
import { CheckboxField } from "@makeplane/propel/components/checkbox-field";
import type { FieldSize } from "@makeplane/propel/components/field";

const SIZES: FieldSize[] = ["lg", "xl", "2xl"];

export default function SizesDemo() {
  return (
    <div className="flex flex-col gap-4">
      {SIZES.map((size) => (
        <CheckboxField
          key={size}
          name={`notify-${size}`}
          value={size}
          label={size}
          size={size}
          description="Notify me when a work item is assigned to me."
          hint="You can change this later."
        />
      ))}
    </div>
  );
}
```

### Invalid

Setting `error` marks the field invalid, recoloring the box border to `danger` and showing the error text in place of the hint.

```tsx
import { CheckboxField } from "@makeplane/propel/components/checkbox-field";

export default function InvalidDemo() {
  return (
    <div className="flex flex-col gap-4">
      <CheckboxField name="digest" value="enabled" label="Send me a weekly digest" size="lg" />
      <CheckboxField
        name="terms"
        value="accepted"
        label="Accept the workspace terms"
        size="lg"
        error="You must accept the terms to continue."
      />
    </div>
  );
}
```

### Controlled

```tsx
import { CheckboxField } from "@makeplane/propel/components/checkbox-field";
import * as React from "react";

export default function ControlledDemo() {
  const [checked, setChecked] = React.useState(false);

  return (
    <CheckboxField
      name="autoArchive"
      value="enabled"
      label="Auto-archive completed work items"
      size="lg"
      description="Move items to the archive one week after they are marked done."
      hint={checked ? "Archiving is on." : "Archiving is off."}
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}
```
## API Reference

### CheckboxField

Ready-to-use single checkbox field with label, description, and helper/error text.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` | — | Visible field label. |
| `size` (required) | `"md" \| "lg" \| "xl" \| "2xl"` | — | Label and helper text size. |
| `stretch` | `"auto" \| "full"` | `"auto"` | Width of the clickable label row when `label` is present. Ready-made concern — the elements `CheckboxLabel` requires `stretch` explicitly. |
| `hint` | `ReactNode` | — | Helper text shown below the control. Replaced by `error` when an error is set. |
| `error` | `ReactNode` | — | Error text shown below the control. |
| `description` | `ReactNode` | — | Optional supporting text announced as the checkbox description. |