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

# Date field

> An entered field that stores a calendar date and renders it in a format you configure.

<Info>
  A Date field captures a calendar day. The submitter picks a date, and you control the format of the stored string and any earliest or latest limits.
</Info>

## When to use it

* Launch dates, send dates, due dates, anything that represents a calendar day.
* A date that needs a specific stored format, such as `YYYYMMDD` for use in a code or a URL.
* A date with business-rule limits, such as no past dates or no more than a year out.

<Warning>
  Do not use a Date field when you need a time of day. Date fields store a calendar day only, with no hour or minute.
</Warning>

## How a value is produced

When a submission is saved, Terminus Hub stores the date the submitter picked, or the `default_value` if the field was left blank. The value is built in this order:

1. Reads the picked date, or resolves the `default_value`. A relative default such as `today` or `+7d` resolves to a concrete date at the moment the submission is saved.
2. Formats it from the `format.components`, in their listed order, joined by `format.separator`.

Validation reads the same date and checks it against `min_date` and `max_date`, both of which accept the same absolute or relative expressions as `default_value`.

The order of entries in the `components` array is the order they appear in the rendered string.

## Settings reference

| Setting                      | Required | Default | Description                                                                                                                                     |
| ---------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `format`                     | Yes      | None    | An object with `components` and an optional `separator`.                                                                                        |
| `format.components[].type`   | Yes      | None    | One of `day`, `month`, `year`, `week`.                                                                                                          |
| `format.components[].format` | No       | None    | Per type: day `numeric` or `padded`; month `numeric`, `padded`, `short`, or `long`; year `short` or `full`; week `numeric`, `padded`, or `iso`. |
| `format.separator`           | No       | None    | Text inserted between components.                                                                                                               |
| `default_value`              | No       | None    | An absolute date or a relative expression.                                                                                                      |
| `min_date`                   | No       | None    | Same form as `default_value`. An earlier date fails validation.                                                                                 |
| `max_date`                   | No       | None    | Same form as `default_value`. A later date fails validation.                                                                                    |

Relative expressions use the units `d` (days), `m` (months), and `y` (years), for example `+7d`, `-30d`, `+1m`, `+1y`. The sign is optional, so `5d` and `+5d` mean the same thing. The value `today` resolves to the current day.

## Example

A `launch_date` field in a Campaign URL Builder model:

```yaml theme={null}
name: launch_date
type: date
required: true
settings:
  format:
    components:
      - { type: year, format: full }
      - { type: month, format: padded }
      - { type: day, format: padded }
  default_value: today
  min_date: today
```

A submitter opening a new submission on 2026-11-15 sees `launch_date` pre-filled with that day. The stored value formats as `20261115`: three zero-padded components with no separator. A submitter trying to save a past date such as 2026-10-01 gets a validation error: `Date must be on or after 2026-11-15`.

## Gotchas

* **Relative defaults resolve when the submission is saved, not when the field was created.** A field with `default_value: today` set last year still gives today's date to a submission saved today. The same applies to `min_date: today`.
* **A numeric format sorts; a named-month format does not.** The date is stored as the formatted string you see. `20261115` sorts correctly next to `20261116`. `15-Nov-2026` does not sort by calendar order. When a date feeds a [Concatenation](/reference/fields/concatenation) or a column you sort by, prefer zero-padded numeric components.
* **Weeks are not a relative unit.** Only `d`, `m`, and `y` work in relative expressions, even though `week` is a valid component `type` for formatting. An expression like `+2w` does not resolve.
* **`format` is required.** You cannot save a Date field with no `format`. There is no implicit default format.

## Related

* [Concatenation field](/reference/fields/concatenation): dates often feed a concatenated value, which is why format choice matters.
* [Text field](/reference/fields/text): another entered field, for values that are not calendar dates.
* [Fields](/reference/fields)