# Date field

> Date entry written in the UI's locale: Intl decides the field order, the week start and the numerals, and the calendar is the kit's. A native input is drawn in the BROWSER's language instead, which is a different thing.

- Group: Forms
- Status: stable
- Aliases: datepicker, date-picker, calendar, datetime
- HTML page: https://design.ipmnx.com/components/date-field/
- Spec: https://design.ipmnx.com/design/#nx-date-field

## Preview

**Closed** The placeholder carries the pattern; nothing is captioned under the control while the field is behaving.

```html
<div class="nx-datefield">
  <label class="nx-field__label" for="due">Fällig am</label>
  <div class="nx-datefield__control">
    <input id="due" class="nx-field__input nx-datefield__input"
        value="03.11.2026" inputmode="numeric"
        placeholder="tt.mm.jjjj">
    <button type="button" class="nx-datefield__trigger"
        aria-label="Kalender öffnen" aria-haspopup="dialog"
        aria-expanded="false">
      <svg viewBox="0 0 24 24" width="18" height="18" fill="none"
          stroke="currentColor" stroke-width="1.8"
          aria-hidden="true">
        <rect x="3" y="5" width="18" height="16" rx="3"></rect>
        <path d="M3 10h18M8 3v4M16 3v4"
            stroke-linecap="round"></path>
      </svg>
    </button>
  </div>
  <span class="nx-datefield__pattern">tt.mm.jjjj</span>
</div>
```

```tsx
<NxDateField
  label="Fällig am"
  value={due}
  onChange={setDue}
  locale="de-DE"
  name="dueAt"
  labels={labels}
/>
```

## Variants

### Calendar open

Six weeks always, so the popover never changes height. Today carries a ring, the selection the accent.

```html
<div style="min-block-size:380px">
  <div class="nx-datefield" data-nx-open="">
    <label class="nx-field__label" for="due2">Fällig am</label>
    <div class="nx-datefield__control">
      <input id="due2" class="nx-field__input nx-datefield__input"
          value="03.11.2026" inputmode="numeric">
      <button type="button" class="nx-datefield__trigger"
          aria-label="Kalender öffnen" aria-haspopup="dialog"
          aria-expanded="true">
        <svg viewBox="0 0 24 24" width="18" height="18" fill="none"
            stroke="currentColor" stroke-width="1.8"
            aria-hidden="true">
          <rect x="3" y="5" width="18" height="16" rx="3"></rect>
          <path d="M3 10h18M8 3v4M16 3v4"
              stroke-linecap="round"></path>
        </svg>
      </button>
    </div>
    <span class="nx-datefield__pattern">tt.mm.jjjj</span>
    <div class="nx-datefield__popup" data-nx-drop="down"
        role="dialog" aria-label="Kalender öffnen">
      <div class="nx-datefield__nav">
        <button type="button" aria-label="Voriger Monat">‹</button>
        <span>November 2026</span>
        <button type="button" aria-label="Nächster Monat">›</button>
      </div>
      <table class="nx-datefield__grid" role="grid"
          aria-label="Kalender">
        <thead>
          <tr>
            <th scope="col"><abbr title="Montag">Mo</abbr></th>
            <th scope="col"><abbr title="Dienstag">Di</abbr></th>
            <th scope="col"><abbr title="Mittwoch">Mi</abbr></th>
            <th scope="col"><abbr title="Donnerstag">Do</abbr></th>
            <th scope="col"><abbr title="Freitag">Fr</abbr></th>
            <th scope="col"><abbr title="Samstag">Sa</abbr></th>
            <th scope="col"><abbr title="Sonntag">So</abbr></th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td role="gridcell" aria-selected="false">
              <button type="button" data-nx-outside=""
                  tabindex="-1">26</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" data-nx-outside=""
                  tabindex="-1">27</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" data-nx-outside=""
                  tabindex="-1">28</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" data-nx-outside=""
                  tabindex="-1">29</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" data-nx-outside=""
                  tabindex="-1">30</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" data-nx-outside=""
                  tabindex="-1">31</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">1</button>
            </td>
          </tr>
          <tr>
            <td role="gridcell" aria-selected="false">
              <button type="button" aria-current="date"
                  tabindex="-1">2</button>
            </td>
            <td role="gridcell" aria-selected="true">
              <button type="button" tabindex="-1">3</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">4</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">5</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">6</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">7</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">8</button>
            </td>
          </tr>
          <tr>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">9</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">10</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">11</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">12</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">13</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">14</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">15</button>
            </td>
          </tr>
          <tr>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">16</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">17</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">18</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">19</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">20</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">21</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">22</button>
            </td>
          </tr>
          <tr>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">23</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">24</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">25</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">26</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">27</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">28</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">29</button>
            </td>
          </tr>
          <tr>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">30</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" data-nx-outside=""
                  tabindex="-1">1</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" data-nx-outside=""
                  tabindex="-1">2</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" data-nx-outside=""
                  tabindex="-1">3</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" data-nx-outside=""
                  tabindex="-1">4</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" data-nx-outside=""
                  tabindex="-1">5</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" data-nx-outside=""
                  tabindex="-1">6</button>
            </td>
          </tr>
        </tbody>
      </table>
      <div class="nx-datefield__foot">
        <button type="button">Heute</button>
        <button type="button">Leeren</button>
      </div>
    </div>
  </div>
</div>
```

```tsx
<NxDateField
  label="Fällig am"
  value={due}
  onChange={setDue}
  locale="de-DE"
  labels={labels}
/>
```

### Typing that stopped parsing

The pattern is an answer to a wrong guess, not a caption: `data-nx-unparsed` brings it on screen and warms the border until the text parses again or blur reverts it.

```html
<div class="nx-datefield" data-nx-unparsed="">
  <label class="nx-field__label" for="due4">Fällig am</label>
  <div class="nx-datefield__control">
    <input id="due4" class="nx-field__input nx-datefield__input"
        value="nächsten Dienstag" inputmode="numeric">
    <button type="button" class="nx-datefield__trigger"
        aria-label="Kalender öffnen" aria-haspopup="dialog"
        aria-expanded="false">
      <svg viewBox="0 0 24 24" width="18" height="18" fill="none"
          stroke="currentColor" stroke-width="1.8"
          aria-hidden="true">
        <rect x="3" y="5" width="18" height="16" rx="3"></rect>
        <path d="M3 10h18M8 3v4M16 3v4"
            stroke-linecap="round"></path>
      </svg>
    </button>
  </div>
  <span class="nx-datefield__pattern">tt.mm.jjjj</span>
</div>
```

```tsx
<NxDateField
  label="Fällig am"
  value={due}
  onChange={setDue}
  locale="de-DE"
  labels={labels}
/>
```

### A window the field will not leave

min/max strike the days out instead of removing them, so the arrow keys still cross the edge. The caption becomes the window, which needs no translating.

```html
<div style="min-block-size:300px">
  <div class="nx-datefield" data-nx-open="" data-nx-refused="">
    <label class="nx-field__label" for="due5">Zahlung am</label>
    <div class="nx-datefield__control">
      <input id="due5" class="nx-field__input nx-datefield__input"
          value="20.10.2026">
      <button type="button" class="nx-datefield__trigger"
          aria-label="Kalender öffnen" aria-expanded="true">
        <svg viewBox="0 0 24 24" width="18" height="18" fill="none"
            stroke="currentColor" stroke-width="1.8"
            aria-hidden="true">
          <rect x="3" y="5" width="18" height="16" rx="3"></rect>
          <path d="M3 10h18M8 3v4M16 3v4"
              stroke-linecap="round"></path>
        </svg>
      </button>
    </div>
    <span class="nx-datefield__pattern">≤ 12.10.2026</span>
    <div class="nx-datefield__popup" data-nx-drop="down"
        role="dialog" aria-label="Kalender">
      <div class="nx-datefield__nav">
        <button type="button" aria-label="Voriger Monat">‹</button>
        <span>Oktober 2026</span>
        <button type="button" aria-label="Nächster Monat">›</button>
      </div>
      <table class="nx-datefield__grid" role="grid"
          aria-label="Kalender">
        <thead>
          <tr>
            <th scope="col"><abbr title="Montag">Mo</abbr></th>
            <th scope="col"><abbr title="Dienstag">Di</abbr></th>
            <th scope="col"><abbr title="Mittwoch">Mi</abbr></th>
            <th scope="col"><abbr title="Donnerstag">Do</abbr></th>
            <th scope="col"><abbr title="Freitag">Fr</abbr></th>
            <th scope="col"><abbr title="Samstag">Sa</abbr></th>
            <th scope="col"><abbr title="Sonntag">So</abbr></th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">5</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">6</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">7</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">8</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">9</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">10</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" tabindex="-1">11</button>
            </td>
          </tr>
          <tr>
            <td role="gridcell" aria-selected="false">
              <button type="button" aria-current="date"
                  tabindex="0">12</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" aria-disabled="true"
                  tabindex="-1">13</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" aria-disabled="true"
                  tabindex="-1">14</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" aria-disabled="true"
                  tabindex="-1">15</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" aria-disabled="true"
                  tabindex="-1">16</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" aria-disabled="true"
                  tabindex="-1">17</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" aria-disabled="true"
                  tabindex="-1">18</button>
            </td>
          </tr>
          <tr>
            <td role="gridcell" aria-selected="false">
              <button type="button" aria-disabled="true"
                  tabindex="-1">19</button>
            </td>
            <td role="gridcell" aria-selected="true">
              <button type="button" aria-disabled="true"
                  tabindex="-1">20</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" aria-disabled="true"
                  tabindex="-1">21</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" aria-disabled="true"
                  tabindex="-1">22</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" aria-disabled="true"
                  tabindex="-1">23</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" aria-disabled="true"
                  tabindex="-1">24</button>
            </td>
            <td role="gridcell" aria-selected="false">
              <button type="button" aria-disabled="true"
                  tabindex="-1">25</button>
            </td>
          </tr>
        </tbody>
      </table>
      <div class="nx-datefield__foot">
        <button type="button">Heute</button>
        <button type="button">Leeren</button>
      </div>
    </div>
  </div>
</div>
```

```tsx
<NxDateField
  label="Zahlung am"
  value={paid}
  onChange={setPaid}
  locale="de-DE"
  max={today}
  labels={labels}
/>
```

### Date and time

`withTime` adds a lenient clock input (9, 930, 9:30 and 9 pm all land), and the value becomes YYYY-MM-DDTHH:mm.

```html
<div class="nx-datefield">
  <label class="nx-field__label" for="met">Begegnung</label>
  <div class="nx-datefield__control">
    <input id="met" class="nx-field__input nx-datefield__input"
        value="03.11.2026" inputmode="numeric">
    <input class="nx-field__input nx-datefield__time" value="14:30"
        aria-label="Uhrzeit" inputmode="numeric">
    <button type="button" class="nx-datefield__trigger"
        aria-label="Kalender öffnen" aria-haspopup="dialog"
        aria-expanded="false">
      <svg viewBox="0 0 24 24" width="18" height="18" fill="none"
          stroke="currentColor" stroke-width="1.8"
          aria-hidden="true">
        <rect x="3" y="5" width="18" height="16" rx="3"></rect>
        <path d="M3 10h18M8 3v4M16 3v4"
            stroke-linecap="round"></path>
      </svg>
    </button>
  </div>
  <span class="nx-datefield__pattern">tt.mm.jjjj</span>
</div>
```

```tsx
<NxDateField
  label="Begegnung"
  value={met}
  onChange={setMet}
  locale="de-DE"
  withTime
  labels={labels}
/>
```

## API

### React props (NxKit)

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` |   | yes | Visible label, tied to the text input. |
| `value` | `string` |   | yes | "", "YYYY-MM-DD" or "YYYY-MM-DDTHH:mm", the shape the native input would have submitted. |
| `onChange` | `(value: string) => void` |   | yes | Called with the ISO shape, or "" when cleared, never with a half-typed date. |
| `labels` | `NxDateFieldLabels` |   | yes | open / clear / previousMonth / nextMonth / today, plus time when withTime, plus unit to translate the dd-mm-yyyy letters. |
| `locale` | `string` | `runtime default` |   | BCP-47 tag of the UI. en-GB writes 03/11/2026 where en-US writes 11/03/2026. |
| `withTime` | `boolean` | `false` |   | Adds the clock input and extends the value to YYYY-MM-DDTHH:mm. |
| `name` | `string` | `undefined` |   | Emits a hidden input, so the field works in a plain FormData submit. |
| `defaultTime` | `string` | `"09:00"` |   | Clock time given to a date picked while no time is set. |
| `required` | `boolean` | `false` |   | Lands on the visible input, because a hidden input is excluded from constraint validation. Still validate on the server. |
| `hideLabel` | `boolean` | `false` |   | Keeps the label for screen readers and takes it off the screen, for one-line filter rows. |
| `min` | `string` | `undefined` |   | Earliest allowed day (YYYY-MM-DD). Earlier days are struck through and refuse the click; a typed one is not emitted. |
| `max` | `string` | `undefined` |   | Latest allowed day (YYYY-MM-DD). |
| `className` | `string` | `""` |   | Added to the positioning root. |
| `disabled` | `boolean` | `false` |   | Disables input, clock and trigger. |
| `hint` | `React.ReactNode` | `undefined` |   | Help text under the control. The workspace time zone belongs here. |
| `error` | `React.ReactNode` | `undefined` |   | Error text; also sets aria-invalid. |

### Classes

| Class | Description |
| --- | --- |
| `.nx-datefield` | Positioning root; carries data-nx-open |
| `.nx-datefield__control` | Row: text input, optional clock, trigger |
| `.nx-datefield__pattern` | The locale's typing pattern; off-screen until data-nx-unparsed |
| `.nx-datefield__popup` | Calendar surface; data-nx-drop flips it above the field |
| `.nx-datefield__grid` | role=grid table, six weeks, roving tabindex; aria-disabled days are struck through |
| `.nx-datefield__foot` | Today / clear row |

## States

### error

```html
<div class="nx-datefield"><label class="nx-field__label" for="due3">Fällig am</label><div class="nx-datefield__control"><input id="due3" class="nx-field__input nx-datefield__input" value="31.02.2026" aria-invalid="true"><button type="button" class="nx-datefield__trigger" aria-label="Kalender öffnen"><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true"><rect x="3" y="5" width="18" height="16" rx="3"></rect><path d="M3 10h18M8 3v4M16 3v4" stroke-linecap="round"></path></svg></button></div><span class="nx-field__error"><span aria-hidden="true">✕</span> Diesen Tag gibt es nicht.</span></div>
```

### disabled

```html
<div class="nx-datefield"><label class="nx-field__label" for="due4">Fällig am</label><div class="nx-datefield__control"><input id="due4" class="nx-field__input nx-datefield__input" value="03.11.2026" disabled><button type="button" class="nx-datefield__trigger" aria-label="Kalender öffnen" disabled><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true"><rect x="3" y="5" width="18" height="16" rx="3"></rect><path d="M3 10h18M8 3v4M16 3v4" stroke-linecap="round"></path></svg></button></div><span class="nx-datefield__pattern">tt.mm.jjjj</span></div>
```

## Accessibility

- Typing is always possible; the calendar is an addition, never the only way in. A date picker that can only be clicked is unusable with a screen reader and slow for everyone else.
- The popover is a dialog over a role=grid with one roving tabindex: arrows move a day, Page a month (Shift a year), Home/End the ends of the week, Escape returns focus to the input.
- Each day button is named by its full date (Intl dateStyle:long), not by its number, and today carries aria-current="date".

## Do / Don't

- Do: Pass the UI's locale (the same tag the page renders in), so the field order matches every other date on the page.
- Don't fall back to `<input type="date">` for "just a date": it is drawn in the browser's language, so it will contradict the page under half your users.
- Do: Say the time zone in `hint` when the value is a moment rather than a day.
- Don't reformat the value on every keystroke: the caret jumps and typed separators vanish.

## Related

- [Field](https://design.ipmnx.com/components/field.md)
- [Select](https://design.ipmnx.com/components/select.md)

---

Source: registry.js (NX Design System)
