| title |
aliases |
tags |
sources |
created |
updated |
| Checkbox Field |
| checkbox-field |
| payload-checkbox |
|
| payloadcms |
| fields |
| boolean |
| checkbox |
|
|
2026-05-15 |
2026-05-15 |
Overview
The Checkbox Field stores a boolean value in the database. It renders as a toggle/checkbox in the Admin Panel.
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 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)hidden: true keeps the field in the DB but removes it from all API responses and Admin UI — use for internal flagsvirtual: 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)
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)
'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
Sources
