obsidian/wiki/payloadcms/fields-date.md

---
title: "Date Field"
aliases: [payload-date-field, date-field, datetime-field]
tags: [payloadcms, fields, date, timezone, react-datepicker]
sources: [raw/fields__date.md]
created: 2026-05-15
updated: 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`.

```ts
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](https://date-fns.org/v4.1.0/docs/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

```ts
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`.

```ts
{
  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:

```ts
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

```ts
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:

```tsx
// 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|Fields: Basic]] — overview of all scalar field types
- [[wiki/payloadcms/fields-checkbox|Checkbox Field]] — another scalar field example
- [[wiki/payloadcms/database-indexes|Database Indexes]] — add `index: true` for date queries
- [[wiki/payloadcms/localization|Localization]] — using `localized: true` on date fields
- [[wiki/payloadcms/authentication-token-data|Token Data (saveToJWT)]] — embed date in JWT

## Sources

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