# Field: Button Checkbox (category: toggle)

URL: https://docs.forms.saastro.io/docs/button-checkbox

<FieldPreview name="button-checkbox" description="Interactive demo of button checkbox field" />

## Overview

The button checkbox field presents checkbox options as toggleable buttons. Users can select multiple options with a more visual, compact interface than traditional checkboxes.

## Usage

### Basic Button Checkbox

```tsx

const config = FormBuilder.create('form')
  .addField('days', (f) =>
    f
      .type('button-checkbox')
      .label('Available Days')
      .options([
        { label: 'Mon', value: 'mon' },
        { label: 'Tue', value: 'tue' },
        { label: 'Wed', value: 'wed' },
        { label: 'Thu', value: 'thu' },
        { label: 'Fri', value: 'fri' },
      ])
      .required('Select at least one day'),
  )
  .addStep('main', ['days'])
  .build();
```

### With Default Values

```tsx
.addField('features', (f) =>
  f.type('button-checkbox')
    .label('Features')
    .options([
      { label: 'WiFi', value: 'wifi' },
      { label: 'Parking', value: 'parking' },
      { label: 'Pool', value: 'pool' },
      { label: 'Gym', value: 'gym' },
    ])
    .value(['wifi', 'parking'])
    .optional()
)
```

### With Selection Limits

```tsx
.addField('toppings', (f) =>
  f.type('button-checkbox')
    .label('Toppings')
    .helperText('Choose up to 3 toppings')
    .options([
      { label: 'Cheese', value: 'cheese' },
      { label: 'Pepperoni', value: 'pepperoni' },
      { label: 'Mushrooms', value: 'mushrooms' },
      { label: 'Olives', value: 'olives' },
      { label: 'Peppers', value: 'peppers' },
    ])
    .required()
    .itemCount(1, 3)
)
```

### JSON Configuration

```json
{
  "type": "button-checkbox",
  "label": "Available Days",
  "options": [
    { "label": "Mon", "value": "mon" },
    { "label": "Tue", "value": "tue" },
    { "label": "Wed", "value": "wed" },
    { "label": "Thu", "value": "thu" },
    { "label": "Fri", "value": "fri" }
  ],
  "value": ["mon", "wed", "fri"],
  "schema": { "required": true, "minItems": 1 }
}
```

## Props

| Prop               | Type                                                  | Default | Description                       |
| ------------------ | ----------------------------------------------------- | ------- | --------------------------------- |
| `type`             | `'button-checkbox'`                                   | -       | Field type (required)             |
| `label`            | `string`                                              | -       | Group label                       |
| `helperText`       | `string`                                              | -       | Help text below field             |
| `options`          | `Option[]`                                            | -       | Array of button options           |
| `value`            | `string[]`                                            | `[]`    | Default selected values           |
| `optionsClassName` | `string`                                              | -       | CSS classes for buttons container |
| `columns`          | `Partial<Record<Breakpoint, number>>`                 | -       | Grid columns by breakpoint        |
| `disabled`         | `boolean \| function \| ConditionGroup`               | `false` | Disable all buttons               |
| `hidden`           | `boolean \| function \| ConditionGroup \| Responsive` | `false` | Hide the field                    |

## Validation

### At Least One Selection

```tsx
.addField('skills', (f) =>
  f.type('button-checkbox')
    .label('Skills')
    .options([...])
    .required('Select at least one skill')
)
```

### Selection Range

```tsx
.addField('preferences', (f) =>
  f.type('button-checkbox')
    .label('Preferences')
    .options([...])
    .required()
    .itemCount(2, 4)
)
```

## Styling

### Custom Classes

```tsx
.addField('days', (f) =>
  f.type('button-checkbox')
    .label('Available Days')
    .options([...])
    .required()
    .classNames({
      wrapper: 'bg-muted/30 p-4 rounded-lg',
      label: 'text-lg font-semibold mb-3',
      error: 'text-destructive text-sm',
    })
)
```

### Options Layout with `optionsClassName`

Control button arrangement:

```json
{
  "type": "button-checkbox",
  "label": "Days",
  "optionsClassName": "flex flex-wrap gap-2",
  "options": [...]
}
```

### Responsive Layout

```tsx
.addField('amenities', (f) =>
  f.type('button-checkbox')
    .label('Amenities')
    .options([...])
    .columns({ default: 12, md: 8 })
)
```

### JSON Styling

```json
{
  "type": "button-checkbox",
  "label": "Days",
  "wrapper_className": "bg-muted/30 p-4 rounded-lg",
  "label_className": "text-lg font-semibold",
  "optionsClassName": "inline-flex flex-wrap gap-1",
  "columns": { "default": 12 }
}
```

## Related Fields

- [Checkbox Group](/docs/checkbox-group) - Traditional checkbox list
- [Button Radio](/docs/button-radio) - Single selection buttons
- [Button Card](/docs/button-card) - Card-style selection

## Accessibility

- Uses Radix UI ToggleGroup (multiple mode)
- Keyboard navigation
- ARIA roles for toggle buttons
- Focus visible states