Date field

Display an instant as a date, time, date-time, or relative value.

A date field declares a calendar date, an instant, or a wall clock time. The precision option determines the value format on the wire. The renderer applies the selected format and its locale rules.

API

fields.date<Name extends string>(
  name: Name,
  options?: DateFieldOptions
): DateFieldBuilder<Name>

Option	Input	Result
`label`	`string`	Sets the text shown for the field.
`description`	`string`	Adds supporting text for the label.
`displayVariant`	`date`, `datetime`, `time`, `relative`	Selects how much date detail to show.
`inputVariant`	`picker` or `input`	Selects the form control.

configure(options) returns a configured clone. clone() returns an independent copy with the same options.

Basic date field

If you do not set a format, a renderer can use its default date presentation.

import {
  datalist,
  defineResource,
  fields,
} from '@backlit/sdk'

const orders = defineResource('orders', [
  fields.date('placedAt', { label: 'Placed' }),
])

orders.view('detail', () =>
  datalist({
    placedAt: '2026-08-12T09:30:00.000Z',
  }).setFields(orders.pick('placedAt'))
)

export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "detail",
    "slots": {
      "content": [
        {
          "kind": "datalist",
          "fields": [
            {
              "kind": "date",
              "name": "placedAt",
              "label": "Placed"
            }
          ],
          "data": {
            "placedAt": "2026-08-12T09:30:00.000Z"
          }
        }
      ]
    }
  }
}

Description

Use a description to explain a deadline, time zone rule, or other date constraint.

import {
  datalist,
  defineResource,
  fields,
} from '@backlit/sdk'

const orders = defineResource('orders', [
  fields.date('deliverBy', {
    label: 'Deliver by',
    description:
      'The carrier must deliver the order before this time.',
  }),
])

orders.view('detail', () =>
  datalist({
    deliverBy: '2026-08-14T17:00:00.000Z',
  }).setFields(orders.pick('deliverBy'))
)

export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "detail",
    "slots": {
      "content": [
        {
          "kind": "datalist",
          "fields": [
            {
              "kind": "date",
              "name": "deliverBy",
              "description": "The carrier must deliver the order before this time.",
              "label": "Deliver by"
            }
          ],
          "data": {
            "deliverBy": "2026-08-14T17:00:00.000Z"
          }
        }
      ]
    }
  }
}

Formats

Date supports four formats.

Format	Use
`date`	A calendar date without a time.
`datetime`	A calendar date and time.
`time`	A time without the calendar date.
`relative`	A value relative to now, such as “2 days ago.”

import {
  datalist,
  defineResource,
  fields,
} from '@backlit/sdk'

const orders = defineResource('orders', [
  fields.date('placedDate', {
    label: 'Date',
    displayVariant: 'date',
  }),
  fields.date('placedAt', {
    label: 'Date and time',
    displayVariant: 'datetime',
  }),
  fields.date('dispatchTime', {
    label: 'Time',
    displayVariant: 'time',
  }),
  fields.date('updatedAt', {
    label: 'Relative',
    displayVariant: 'relative',
  }),
])

orders.view('detail', () =>
  datalist({
    placedDate: '2026-08-12T09:30:00.000Z',
    placedAt: '2026-08-12T09:30:00.000Z',
    dispatchTime: '2026-08-12T16:45:00.000Z',
    updatedAt: '2026-08-13T09:30:00.000Z',
  }).setFields(
    orders.pick(
      'placedDate',
      'placedAt',
      'dispatchTime',
      'updatedAt'
    )
  )
)

export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "detail",
    "slots": {
      "content": [
        {
          "kind": "datalist",
          "fields": [
            {
              "kind": "date",
              "name": "placedDate",
              "label": "Date",
              "displayVariant": "date"
            },
            {
              "kind": "date",
              "name": "placedAt",
              "label": "Date and time",
              "displayVariant": "datetime"
            },
            {
              "kind": "date",
              "name": "dispatchTime",
              "label": "Time",
              "displayVariant": "time"
            },
            {
              "kind": "date",
              "name": "updatedAt",
              "label": "Relative",
              "displayVariant": "relative"
            }
          ],
          "data": {
            "placedDate": "2026-08-12T09:30:00.000Z",
            "placedAt": "2026-08-12T09:30:00.000Z",
            "dispatchTime": "2026-08-12T16:45:00.000Z",
            "updatedAt": "2026-08-13T09:30:00.000Z"
          }
        }
      ]
    }
  }
}

Input variants

Use picker for a visual date control. Use input for direct text entry. The variant does not change the read-only date.

import {
  datalist,
  defineResource,
  fields,
} from '@backlit/sdk'

const orders = defineResource('orders', [
  fields.date('deliverOn', {
    label: 'Deliver on',
    inputVariant: 'picker',
  }),
  fields.date('dispatchAt', {
    label: 'Dispatch at',
    inputVariant: 'input',
  }),
])

orders.view('detail', () =>
  datalist({
    deliverOn: '2026-08-14T00:00:00.000Z',
    dispatchAt: '2026-08-13T09:30:00.000Z',
  }).setFields(orders.pick('deliverOn', 'dispatchAt'))
)

export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "detail",
    "slots": {
      "content": [
        {
          "kind": "datalist",
          "fields": [
            {
              "kind": "date",
              "name": "deliverOn",
              "inputVariant": "picker",
              "label": "Deliver on"
            },
            {
              "kind": "date",
              "name": "dispatchAt",
              "inputVariant": "input",
              "label": "Dispatch at"
            }
          ],
          "data": {
            "deliverOn": "2026-08-14T00:00:00.000Z",
            "dispatchAt": "2026-08-13T09:30:00.000Z"
          }
        }
      ]
    }
  }
}

Clone

Use configure when two contexts need different date variants for the same key.

import {
  datalist,
  defineResource,
  fields,
} from '@backlit/sdk'

const updatedAt = fields.date('updatedAt', {
  label: 'Updated',
  displayVariant: 'datetime',
})
const orders = defineResource('orders', [
  updatedAt.configure({ displayVariant: 'relative' }),
])

orders.view('detail', () =>
  datalist({
    updatedAt: '2026-08-13T09:30:00.000Z',
  }).setFields(orders.pick('updatedAt'))
)

export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "detail",
    "slots": {
      "content": [
        {
          "kind": "datalist",
          "fields": [
            {
              "kind": "date",
              "name": "updatedAt",
              "label": "Updated",
              "displayVariant": "relative"
            }
          ],
          "data": {
            "updatedAt": "2026-08-13T09:30:00.000Z"
          }
        }
      ]
    }
  }
}

All options

You can use a label, description, format, and input variant on the same date field.

import {
  datalist,
  defineResource,
  fields,
} from '@backlit/sdk'

const orders = defineResource('orders', [
  fields.date('deliverBy', {
    label: 'Deliver by',
    description:
      'The carrier must deliver the order before this time.',
    displayVariant: 'datetime',
    inputVariant: 'picker',
  }),
])

orders.view('detail', () =>
  datalist({
    deliverBy: '2026-08-14T17:00:00.000Z',
  }).setFields(orders.pick('deliverBy'))
)

export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "detail",
    "slots": {
      "content": [
        {
          "kind": "datalist",
          "fields": [
            {
              "kind": "date",
              "name": "deliverBy",
              "description": "The carrier must deliver the order before this time.",
              "inputVariant": "picker",
              "label": "Deliver by",
              "displayVariant": "datetime"
            }
          ],
          "data": {
            "deliverBy": "2026-08-14T17:00:00.000Z"
          }
        }
      ]
    }
  }
}

Precision, time zone, and limits

precision accepts day, datetime, or time. The default is datetime. day sends YYYY-MM-DD. datetime sends an ISO instant in UTC with Z. time sends HH:mm. Only datetime uses timeZone, an IANA time zone name. Without a field time zone, the client context supplies the zone.

min and max set picker bounds in the precision’s wire format. minuteStep sets the time step; the default is one minute. Display variants change presentation. They do not change precision or its wire format.

import {
  datalist,
  defineResource,
  fields,
} from '@backlit/sdk'
const orders = defineResource('orders', [
  fields.date('day', {
    precision: 'day',
    min: '2026-01-01',
    max: '2026-12-31',
  }),
  fields.date('at', {
    precision: 'datetime',
    timeZone: 'Asia/Kolkata',
    minuteStep: 15,
  }),
  fields.date('time', { precision: 'time' }),
])
orders.view('detail', () =>
  datalist({
    day: '2026-09-19',
    at: '2026-09-19T10:00:00Z',
    time: '15:30',
  }).setFields(orders.pick('day', 'at', 'time'))
)
export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "detail",
    "slots": {
      "content": [
        {
          "kind": "datalist",
          "fields": [
            {
              "kind": "date",
              "name": "day",
              "precision": "day",
              "min": "2026-01-01",
              "max": "2026-12-31",
              "label": ""
            },
            {
              "kind": "date",
              "name": "at",
              "precision": "datetime",
              "timeZone": "Asia/Kolkata",
              "minuteStep": 15,
              "label": ""
            },
            {
              "kind": "date",
              "name": "time",
              "precision": "time",
              "label": ""
            }
          ],
          "data": {
            "day": "2026-09-19",
            "at": "2026-09-19T10:00:00.000Z",
            "time": "15:30"
          }
        }
      ]
    }
  }
}