obsidian/wiki/payloadcms/fields-date.md

title	aliases	tags	sources	created	updated
Date Field	payload-date-field date-field datetime-field	payloadcms fields date timezone react-datepicker	raw/fields__date.md	2026-05-15	2026-05-15

Overview

The Date field saves a Date value in the database and renders a react-datepicker UI in the Admin Panel. Storage format is always ISO 8601: YYYY-MM-DDTHH:mm:ss.SSSZ.

import type { Field } from 'payload'

export const MyDateField: Field = {
  name: 'publishedAt',
  type: 'date',
}

Config Options

Option	Description
name *	DB property name
label	Admin Panel label (string or i18n object)
index	Build DB index for fast queries
validate	Custom validation (runs on both client + server)
saveToJWT	Include in JWT if top-level on auth collection
hooks	Field lifecycle hooks
access	Field-level access control
hidden	Hide from all APIs + Admin Panel (still saved to DB)
defaultValue	Default date value
localized	Enable per-locale date values
required	Make field required
timezone	Enable timezone picker (true or config object)
virtual	Disable DB column (true) or link to relationship

Admin Options

Nested under admin.date:

Property	Description
placeholder	Input placeholder text
displayFormat	Format in list-view cells (unicode date format via date-fns)
pickerAppearance	dayAndTime | timeOnly | dayOnly | monthOnly (default: dayOnly)
monthsToShow	1 or 2 months in datepicker
minDate / maxDate	Restrict selectable date range
minTime / maxTime	Restrict selectable time range
timeIntervals	Minutes between time options (default: 30)
timeFormat	Time display format (default: 'h:mm aa')
overrides	Pass any prop directly to react-datepicker

Display Format vs Picker Appearance

• displayFormat affects only the cell in list view — takes any unicode date format
• pickerAppearance controls the datepicker widget — when set alone, cell format auto-matches
• Stored value is always full ISO 8601 regardless of display settings

Example: Multiple Appearance Modes

fields: [
  {
    name: 'dateOnly',
    type: 'date',
    admin: { date: { pickerAppearance: 'dayOnly', displayFormat: 'd MMM yyy' } },
  },
  {
    name: 'timeOnly',
    type: 'date',
    admin: { date: { pickerAppearance: 'timeOnly', displayFormat: 'h:mm:ss a' } },
  },
  {
    name: 'monthOnly',
    type: 'date',
    admin: { date: { pickerAppearance: 'monthOnly', displayFormat: 'MMMM yyyy' } },
  },
]

Timezones

Enable with timezone: true — adds a dropdown to the datepicker. The selected timezone is stored in a separate column <fieldName>_tz.

{
  name: 'publishedAt',
  type: 'date',
  timezone: {
    defaultTimezone: 'America/New_York',
    supportedTimezones: [
      { label: 'New York', value: 'America/New_York' },
      { label: 'London', value: 'Europe/London' },
    ],
  },
}

Timezone Option	Description
defaultTimezone	Pre-selected timezone
supportedTimezones	Array of { label, value }
required	Require timezone even if date is optional
override	Function to customize the auto-generated select field

Important: The date itself is stored in UTC. Your frontend is responsible for converting to the user's timezone. Dates without a time are normalised to 12:00 in the selected timezone.

Custom UTC Offsets

Use ±HH:mm format alongside IANA names:

supportedTimezones: [
  { label: 'UTC+5:30 (India)', value: '+05:30' },
  { label: 'New York', value: 'America/New_York' },
]

UTC offsets are fixed — no DST handling. Use IANA names for DST awareness.

Timezone Override Function

timezone: {
  override: ({ baseField }) => ({
    ...baseField,
    admin: { ...baseField.admin, disabled: { column: true } },
  }),
}

GraphQL Enum Names for UTC Offsets

Offset	GraphQL Enum
+05:30	_TZOFFSET_PLUS_05_30
-08:00	_TZOFFSET_MINUS_08_00
+00:00	_TZOFFSET_PLUS_00_00

IANA names are also transformed (e.g. America/New_York → America_New_York). REST API returns the raw value.

Custom Components

Use DateTimeField from @payloadcms/ui for both server and client component slots:

// Server
import { DateTimeField } from '@payloadcms/ui'
import type { DateFieldServerComponent } from 'payload'

export const CustomDateFieldServer: DateFieldServerComponent = ({
  clientField, path, schemaPath, permissions,
}) => <DateTimeField field={clientField} path={path} schemaPath={schemaPath} permissions={permissions} />

Key Takeaways

• Storage is always ISO 8601 UTC — display format only affects Admin Panel UI
• pickerAppearance drives what parts of the date are selectable (dayOnly, timeOnly, dayAndTime, monthOnly)
• Timezone support requires timezone: true — creates a separate <name>_tz DB column
• Dates stored UTC; frontend must handle conversion for display
• UTC offset values (+05:30) don't handle DST — prefer IANA names for production use
• displayFormat uses date-fns unicode format strings
• admin.date.overrides lets you pass any prop directly to react-datepicker

Related

• wiki/payloadcms/fields-basic — overview of all scalar field types
• wiki/payloadcms/fields-checkbox — another scalar field example
• wiki/payloadcms/database-indexes — add index: true for date queries
• wiki/payloadcms/localization — using localized: true on date fields
• wiki/payloadcms/authentication-token-data — embed date in JWT

Sources

• raw/fields__date.md — https://payloadcms.com/docs/fields/date