---
title: Date field
description: 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

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

<BacklitExample path="fields/date/basic" view="detail" />

## Description

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

<BacklitExample path="fields/date/description" view="detail" />

## 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." |

<BacklitExample path="fields/date/formats" view="detail" />

## Input variants

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

<BacklitExample path="fields/date/input_variants" view="detail" />

## Clone

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

<BacklitExample path="fields/date/clone" view="detail" />

## All options

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

<BacklitExample path="fields/date/all_options" view="detail" />

## 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.

<BacklitExample path="fields/date/precision" view="detail" />