---
title: "Checkbox Field"
aliases: [checkbox-field, payload-checkbox]
tags: [payloadcms, fields, boolean, checkbox]
sources: [raw/fields__checkbox.md]
created: 2026-05-15
updated: 2026-05-15
---

## Overview

The Checkbox Field stores a **boolean** value in the database. It renders as a toggle/checkbox in the Admin Panel.

```ts
import type { Field } from 'payload'

export const MyCheckboxField: Field = {
  name: 'enableCoolStuff',
  type: 'checkbox',
  label: 'Click me to see fanciness',
  defaultValue: false,
}
```

## Config Options

| Option | Required | Description |
|--------|----------|-------------|
| `name` | Yes | Property name in DB and API responses |
| `label` | No | Admin Panel label (string or i18n object) |
| `defaultValue` | No | Boolean default; defaults to `false` if field is also `required` |
| `required` | No | Require a truthy value |
| `validate` | No | Custom validation function (runs on both client and server) |
| `index` | No | Add DB index for faster queries |
| `saveToJWT` | No | Include value in user JWT (top-level auth collections only) |
| `hooks` | No | Field-level hooks |
| `access` | No | Field-level access control |
| `hidden` | No | Hide from API and Admin Panel (still saved to DB) |
| `localized` | No | Per-locale values — requires [[wiki/payloadcms/localization\|localization]] enabled |
| `admin` | No | Admin-specific config (description, condition, components…) |
| `virtual` | No | `true` to skip DB column, or string path to link with a relationship |
| `typescriptSchema` | No | Override generated TS type with custom JSON schema |
| `custom` | No | Arbitrary plugin extension data |

## Key Takeaways

- Stores a plain boolean — simplest scalar field type in Payload
- `defaultValue` falls back to `false` automatically when `required: true`
- Use `index: true` if you filter/query by this field frequently (e.g. `isPublished`, `isActive`)
- `saveToJWT: true` embeds the value into the auth token — useful for feature flags per user without extra DB lookups (see [[wiki/payloadcms/authentication-token-data\|Token Data]])
- `hidden: true` keeps the field in the DB but removes it from all API responses and Admin UI — use for internal flags
- `virtual: true` removes the DB column entirely — field exists only in memory/logic
- Supports custom Server and Client Components for both the field wrapper and the label

## Custom Components

### Custom Field (Server)

```tsx
import { CheckboxField } from '@payloadcms/ui'
import type { CheckboxFieldServerComponent } from 'payload'

export const CustomCheckboxFieldServer: CheckboxFieldServerComponent = ({
  clientField, path, schemaPath, permissions,
}) => (
  <CheckboxField field={clientField} path={path} schemaPath={schemaPath} permissions={permissions} />
)
```

### Custom Field (Client)

```tsx
'use client'
import { CheckboxField } from '@payloadcms/ui'
import type { CheckboxFieldClientComponent } from 'payload'

export const CustomCheckboxFieldClient: CheckboxFieldClientComponent = (props) => (
  <CheckboxField {...props} />
)
```

### Custom Label

Use `CheckboxFieldLabelServerComponent` / `CheckboxFieldLabelClientComponent` with `FieldLabel` from `@payloadcms/ui`. Pass `label`, `path`, and `required` props.

## Related

- [[wiki/payloadcms/fields-basic\|Fields: Basic]] — overview of all scalar fields
- [[wiki/payloadcms/fields-complex\|Fields: Complex]] — arrays, blocks, relationships
- [[wiki/payloadcms/authentication-token-data\|Authentication — Token Data]] — `saveToJWT` pattern
- [[wiki/payloadcms/database-indexes\|Database Indexes]] — when and how to add `index: true`
- [[wiki/payloadcms/access-control\|Access Control]] — field-level access

## Sources

- `raw/fields__checkbox.md` — https://payloadcms.com/docs/fields/checkbox