# Checkbox

> Binary selection control for boolean values.

**URL:** https://inference.sh/docs/agents/widgets/checkbox
**Last updated:** 2026-09-18

---

Binary selection control for boolean values.

## Preview

```
☐ Subscribe to updates
```

## Usage

```go
node := models.WidgetNode{
    Type:  models.WidgetNodeTypeCheckbox,
    Name:  "accept_terms",
    Label: "I accept the terms and conditions",
}
```

## Props

| Name | Type | Description | Default |
|------|------|-------------|---------|
| `type` | `"checkbox"` | Node type | required |
| `name` | `string` | Form field name (key in form data) | required |
| `label` | `string` | Label text displayed next to checkbox | - |
| `defaultChecked` | `boolean` | Initial checked state | `false` |
| `onCheckedChangeAction` | `WidgetAction` | Action triggered when checkbox is toggled | - |

## Examples

### Basic Checkbox

```go
{
    Type:  models.WidgetNodeTypeCheckbox,
    Name:  "newsletter",
    Label: "Subscribe to newsletter",
}
```

### Pre-checked

```go
{
    Type:           models.WidgetNodeTypeCheckbox,
    Name:           "notifications",
    Label:          "Enable notifications",
    DefaultChecked: true,
}
```

### Checkbox with Action

Trigger an action immediately when the checkbox is toggled:

```go
{
    Type:           models.WidgetNodeTypeCheckbox,
    Name:           "task_completed",
    Label:          "Mark task as complete",
    DefaultChecked: false,
    OnCheckedChangeAction: &models.WidgetAction{
        Type:    "toggle_task",
        Payload: map[string]interface{}{"task_id": "123"},
    },
}
```

### Task List Example

```go
{
    Type: models.WidgetNodeTypeCol,
    Gap:  2,
    Children: []models.WidgetNode{
        {Type: models.WidgetNodeTypeTitle, Value: "Today's Tasks", Size: "lg"},
        {
            Type:           models.WidgetNodeTypeCheckbox,
            Name:           "task1",
            Label:          "Review pull requests",
            DefaultChecked: true,
            OnCheckedChangeAction: &models.WidgetAction{
                Type:    "toggle_task",
                Payload: map[string]interface{}{"task_id": 1},
            },
        },
        {
            Type:           models.WidgetNodeTypeCheckbox,
            Name:           "task2",
            Label:          "Deploy to staging",
            OnCheckedChangeAction: &models.WidgetAction{
                Type:    "toggle_task",
                Payload: map[string]interface{}{"task_id": 2},
            },
        },
        {
            Type:           models.WidgetNodeTypeCheckbox,
            Name:           "task3",
            Label:          "Write documentation",
            OnCheckedChangeAction: &models.WidgetAction{
                Type:    "toggle_task",
                Payload: map[string]interface{}{"task_id": 3},
            },
        },
    },
}
```

### Terms Acceptance (with Form Submit)

```go
widget := &models.Widget{
    Type:  models.WidgetTypeUI,
    Title: "Complete Registration",
    Children: []models.WidgetNode{
        {
            Type: models.WidgetNodeTypeCol,
            Gap:  3,
            Children: []models.WidgetNode{
                {Type: models.WidgetNodeTypeInput, Name: "email", Placeholder: "Email"},
                {Type: models.WidgetNodeTypeCheckbox, Name: "accept_terms", Label: "I accept the terms of service"},
                {Type: models.WidgetNodeTypeCheckbox, Name: "accept_privacy", Label: "I accept the privacy policy"},
                {
                    Type:    models.WidgetNodeTypeRow,
                    Gap:     2,
                    Justify: "end",
                    Children: []models.WidgetNode{
                        {
                            Type:    models.WidgetNodeTypeButton,
                            Label:   "Register",
                            Variant: "default",
                            OnClickAction: &models.WidgetAction{
                                Type:            "register",
                                LoadingBehavior: "self",
                            },
                        },
                    },
                },
            },
        },
    },
}
```

## Form Data

When the widget is submitted, checkbox values are included as booleans:

```json
{
  "email": "user@example.com",
  "accept_terms": true,
  "accept_privacy": false
}
```

## TypeScript

```typescript
const node: WidgetNode = {
  type: "checkbox",
  name: "accept_terms",
  label: "I accept the terms",
  defaultChecked: false,
  onCheckedChangeAction: {
    type: "terms_changed",
    payload: { field: "terms" },
  },
}
```

## Best Practices

1. **Use clear labels** - Describe what checking the box means
2. **Positive phrasing** - "Enable X" instead of "Disable X"
3. **Group related checkboxes** - Use Col with gap for visual grouping
4. **Set reasonable defaults** - Pre-check common preferences
5. **Use onCheckedChangeAction for immediate feedback** - Useful for task lists or toggles