96 lines
3.7 KiB
Markdown
96 lines
3.7 KiB
Markdown
---
|
|
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
|