> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frogbot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Date Field

> Store dates and configure date, time, month, and timezone inputs.

The Date field stores an ISO date string and provides a configurable date and time picker in the admin panel.

```ts theme={"theme":"tokyo-night"}
import type { Field } from 'frogbot'

export const PublishedAt: Field = {
  name: 'publishedAt',
  type: 'date',
  admin: {
    date: {
      displayFormat: 'd MMM yyyy, h:mm a',
      pickerAppearance: 'dayAndTime',
    },
  },
}
```

## Config options

| Option | Type | Default | Description |
| - | - | - | - |
| `name` | `string` | Required | Property name used in stored records and APIs. See [field names](https://docs.frogbot.ai/fields/overview.md#field-names). |
| `type` | `'date'` | Required | Selects the Date field. |
| `timezone` | `true \| { defaultTimezone, supportedTimezones, required, override }` | — | Adds a timezone selector stored in `<name>_tz`. See [Timezones](#timezones). |
| `label` | `string \| Record<string, string> \| (({ i18n, t }) => string) \| false` | Generated from `name` | Label shown in the admin panel. Use an object keyed by language code for translations, or `false` to hide the label. |
| `required` | `boolean` | `false` | Rejects an empty value in the default validation. |
| `unique` | `boolean` | `false` | Creates a unique database index for the field path. See [indexes](https://docs.frogbot.ai/database/indexes.md). |
| `index` | `boolean` | `false` | Creates a database index for faster queries. `unique` already creates one. |
| `localized` | `boolean` | `false` | Stores one value per configured locale. Ignored without [localization](https://docs.frogbot.ai/configuration/localization.md) or inside a localized parent. |
| `defaultValue` | `string \| Date` or `({ locale, req, user }) => value` | — | Value used when the field has no value. See [default values](https://docs.frogbot.ai/fields/overview.md#default-values). |
| `validate` | `Validate` | Built-in validator | Replaces the built-in validator. See [validation](https://docs.frogbot.ai/fields/overview.md#validation). |
| `hooks` | `{ beforeValidate, beforeChange, afterChange, afterRead, beforeDuplicate }` | — | Arrays of `FieldHook` functions for each phase. See [field hooks](https://docs.frogbot.ai/hooks/fields.md). |
| `access` | `{ create, read, update }` | Allowed | `FieldAccess` functions for each operation. See [field access control](https://docs.frogbot.ai/access-control/fields.md). |
| `hidden` | `boolean` | `false` | Removes the field from API responses and the admin panel while keeping stored data. |
| `saveToJWT` | `boolean \| string` | `false` | In an auth-enabled collection, copies the value into the user's token. A string sets the token key. See [token data](https://docs.frogbot.ai/authentication/token-data.md). |
| `virtual` | `boolean \| string` | `false` | `true` skips database storage; a string reads a value through a relationship path. Virtual fields are read-only in the admin panel unless `admin.readOnly` is `false`. See [virtual fields](https://docs.frogbot.ai/fields/overview.md#virtual-field-configuration). |
| `disableDuplicate` | `boolean` | `false` | Leaves the value out when a document is duplicated, so the copy uses `defaultValue`. |
| `admin` | `object` | — | Admin-panel options. See [Admin options](#admin-options). |
| `custom` | `Record<string, any>` | — | Server-only metadata for your own code and plugins. Use `admin.custom` for data the browser also needs. |
| `jsonSchema` | `Array<({ jsonSchema }) => JSONSchema4>` | — | Functions that modify the JSON Schema used by [type generation](https://docs.frogbot.ai/typescript/generating-types.md). |

## Admin options

Date fields support the standard [field admin options](https://docs.frogbot.ai/fields/overview.md#admin-options), plus `placeholder` and a `date` object.

| Option | Type | Default | Description |
| - | - | - | - |
| `placeholder` | `string \| Record<string, string>` | — | Placeholder text. Use an object keyed by language code for translations. |
| `date.pickerAppearance` | `'default' \| 'dayAndTime' \| 'dayOnly' \| 'timeOnly' \| 'monthOnly'` | `'default'` | Picker style. `default` and `dayOnly` pick a day, `dayAndTime` adds a time list, `timeOnly` shows only the time list, and `monthOnly` picks a month. |
| `date.displayFormat` | `string` | Depends on `pickerAppearance` | Unicode date format for the picker input and list cells. Defaults to `MM/dd/yyyy` (`default`), `MMM d, yyy h:mm a` (`dayAndTime`), `h:mm a` (`timeOnly`), `MMM dd` (`dayOnly`), or `MMMM` (`monthOnly`). |
| `date.monthsToShow` | `1 \| 2` | `1` | Number of months shown side by side. Day pickers only. |
| `date.minDate` | `Date` | — | Earliest selectable date. Day and month pickers only. |
| `date.maxDate` | `Date` | — | Latest selectable date. Day and month pickers only. |
| `date.minTime` | `Date` | — | Earliest selectable time. Time pickers only. |
| `date.maxTime` | `Date` | — | Latest selectable time. Time pickers only. |
| `date.timeIntervals` | `number` | `30` | Minutes between entries in the time list. Time pickers only. |
| `date.timeFormat` | `string` | `'h:mm aa'` | Format of entries in the time list. Time pickers only. |
| `date.overrides` | `DatePickerProps` | — | Extra `react-datepicker` props merged over the generated ones. |

Picker appearance and display format affect only the admin UI. The complete value is stored as an ISO date string.

### Display format and picker appearance

`displayFormat` accepts a Unicode date format and controls the value shown in the picker input and admin cells. `pickerAppearance` controls whether the picker displays a day and time, day, time, or month. If only `pickerAppearance` is set, the admin panel uses a matching display format.

## Example

```ts theme={"theme":"tokyo-night"}
import type { CollectionConfig } from 'frogbot'

export const Events: CollectionConfig = {
  slug: 'events',
  fields: [
    {
      name: 'dateOnly',
      type: 'date',
      admin: {
        date: {
          displayFormat: 'd MMM yyyy',
          pickerAppearance: 'dayOnly',
        },
      },
    },
    {
      name: 'timeOnly',
      type: 'date',
      admin: {
        date: {
          displayFormat: 'h:mm:ss a',
          pickerAppearance: 'timeOnly',
        },
      },
    },
    {
      name: 'monthOnly',
      type: 'date',
      admin: {
        date: {
          displayFormat: 'MMMM yyyy',
          pickerAppearance: 'monthOnly',
        },
      },
    },
  ],
}
```

## Custom components

### Field

#### Server component

```tsx theme={"theme":"tokyo-night"}
import { DateTimeField } from '@frogbotai/ui/admin'
import type { DateFieldServerProps } from 'frogbot'

export const CustomDateServer = (props: DateFieldServerProps) => (
  <DateTimeField
    field={props.clientField}
    path={props.path}
    permissions={props.permissions}
    schemaPath={props.schemaPath}
  />
)
```

#### Client component

```tsx theme={"theme":"tokyo-night"}
'use client'

import { DateTimeField } from '@frogbotai/ui/admin'
import type { DateFieldClientProps } from 'frogbot'

export const CustomDateClient = (props: DateFieldClientProps) => <DateTimeField {...props} />
```

### Label

#### Server component

```tsx theme={"theme":"tokyo-night"}
import { FieldLabel } from '@frogbotai/ui/admin'
import type { DateFieldLabelServerProps } from 'frogbot'

export const CustomDateLabelServer = ({ clientField, path }: DateFieldLabelServerProps) => (
  <FieldLabel
    label={clientField.label || clientField.name}
    path={path}
    required={clientField.required}
  />
)
```

#### Client component

```tsx theme={"theme":"tokyo-night"}
'use client'

import { FieldLabel } from '@frogbotai/ui/admin'
import type { DateFieldLabelClientProps } from 'frogbot'

export const CustomDateLabelClient = ({ field, path }: DateFieldLabelClientProps) => (
  <FieldLabel label={field.label || field.name} path={path} required={field.required} />
)
```

## Timezones

Set `timezone: true` to show the root admin configuration's supported timezones. The selected timezone is stored in an additional column named `<fieldName>_tz`.

```ts theme={"theme":"tokyo-night"}
import type { Field } from 'frogbot'

export const EventTime: Field = {
  name: 'eventTime',
  type: 'date',
  timezone: {
    defaultTimezone: 'America/New_York',
    required: true,
    supportedTimezones: [
      { label: 'New York', value: 'America/New_York' },
      { label: 'India', value: '+05:30' },
      { label: 'UTC', value: 'UTC' },
    ],
  },
}
```

The timezone object supports these options:

| Option | Type | Default | Description |
| - | - | - | - |
| `defaultTimezone` | `string` | Root `admin.timezones.defaultTimezone` | Initial timezone value. When only one timezone is supported, it becomes the default. |
| `supportedTimezones` | `{ label: string; value: string }[]` | Root `admin.timezones.supportedTimezones` | Timezones editors can choose. Values are IANA names or fixed offsets. |
| `required` | `boolean` | `false` | Requires a timezone even when the date itself is optional. A required date always requires a timezone. |
| `override` | `({ baseField }) => Field` | — | Receives the generated Select field and returns the field to use. See [Timezone override](#timezone-override). |

Dates are stored in UTC. Convert them to the selected timezone when rendering
them in your application. Dates without a specific time are normalized to
noon in the selected timezone.

### Timezone override

Use `override` to modify the generated Select field. The callback receives `baseField`, which includes its generated name, options, default value, required state, label, and hidden admin setting.

```ts theme={"theme":"tokyo-night"}
import type { Field } from 'frogbot'

export const PublishedAt: Field = {
  name: 'publishedAt',
  type: 'date',
  timezone: {
    override: ({ baseField }) => ({
      ...baseField,
      admin: { ...baseField.admin, disabled: { column: true } },
    }),
  },
}
```

Change available timezone options through `supportedTimezones` so FrogBot can
validate the configured values.

### Custom UTC offsets

Fixed offsets use `+HH:mm` or `-HH:mm`:

```ts theme={"theme":"tokyo-night"}
import type { Field } from 'frogbot'

export const ScheduledAt: Field = {
  name: 'scheduledAt',
  type: 'date',
  timezone: {
    supportedTimezones: [
      { label: 'New York', value: 'America/New_York' },
      { label: 'India', value: '+05:30' },
      { label: 'Pacific', value: '-08:00' },
      { label: 'UTC', value: '+00:00' },
    ],
  },
}
```

Fixed offsets do not adjust for daylight saving time. Use an IANA timezone
such as `America/New_York` when daylight saving behavior matters.

If an application separately mounts a compatible GraphQL executor, timezone values are transformed into enum-safe names: `+05:30` becomes `_TZOFFSET_PLUS_05_30`, `-08:00` becomes `_TZOFFSET_MINUS_08_00`, and `America/New_York` becomes `America_New_York`. The original value remains stored and is returned by the REST API. FrogBot does not currently ship a GraphQL execution route.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.