# Date Time Input

> A Date Time Input widget to allow user to enter a date and a time directly via keyboard using segmented inputs

Date Time Input widgets are [Input Fields](https://golemui.com/dx/widgets-reference/input-fields/overview.md) that let the user enter a date and a time together in a single row of segmented inputs, offering a keyboard-friendly alternative to interactive calendars. The segments follow the locale's order, and whether the time renders in 12-hour or 24-hour mode follows the user's locale too.

The widget emits a local ISO date-time string (`YYYY-MM-DDTHH:mm:ss`) on change, pair it with the `{ format: 'date-time' }` validator.


```ts title="datetimeinput.ts"

export default [
  gui.inputs.dateTimeInput('meetingAt', {
    label: 'Meeting At',
  }),
];
```

_Live demo on the docs page. Form definition: [datetimeinput.ts](https://golemui.com/template/widgets-dx/datetimeinput/datetimeinput.ts)._

Typed values clamp at their limits (`30` hours becomes `23` or `12` in 12-hour mode, and `95` minutes becomes `59`). ArrowUp/ArrowDown increment the focused segment: date parts and hours stop at their limits while minutes wrap around (`59` → `00`). The AM/PM segment is a toggle button: clicking it (or pressing Enter, Space, ArrowUp or ArrowDown) swaps AM and PM. If the completed date does not exist (e.g. February 30), the widget shows an error instead of a value; the message can be customized (and localized) with the `invalidDateMessage` prop.

## Props

Use these `props` to customize your Date Time Input widget.

| prop                 | type                  | description                                                                                                                                 |
| -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `dayAriaLabel`       | string                | ARIA label for the day segment input. Defaults to `Day`                                                                                     |
| `dayPeriodAriaLabel` | string                | ARIA label for the AM/PM segment input. Defaults to `AM/PM`                                                                                 |
| `hint`               | string                | A description to display below the segmented inputs                                                                                         |
| `hourAriaLabel`      | string                | ARIA label for the hour segment input. Defaults to `Hour`                                                                                   |
| `hourFormat`         | `'12' \| '24'`        | Forces 12-hour or 24-hour mode; when omitted the locale decides                                                                             |
| `icon`               | string                | A css class to display an icon inside the input                                                                                             |
| `incompleteMessage`  | string \| Localizable | Error message shown when focus leaves the widget with a partially filled date-time behind; the value goes to `null` so validators report it |
| `invalidDateMessage` | string \| Localizable | Error message shown when the completed date does not exist, e.g. February 30                                                                |
| `maxDate`            | string                | Latest allowed date (ISO date, inclusive)                                                                                                   |
| `maxDateMessage`     | string \| Localizable | Error message shown when the entered date is after `maxDate`                                                                                |
| `maxTime`            | string                | Last allowed time (ISO time, inclusive)                                                                                                     |
| `maxTimeMessage`     | string \| Localizable | Error message shown when the entered time is after `maxTime`                                                                                |
| `minDate`            | string                | Earliest allowed date (ISO date, inclusive)                                                                                                 |
| `minDateMessage`     | string \| Localizable | Error message shown when the entered date is before `minDate`                                                                               |
| `minTime`            | string                | First allowed time (ISO time, inclusive)                                                                                                    |
| `minTimeMessage`     | string \| Localizable | Error message shown when the entered time is before `minTime`                                                                               |
| `minuteAriaLabel`    | string                | ARIA label for the minute segment input. Defaults to `Minute`                                                                               |
| `minuteStep`         | number                | The ArrowUp/ArrowDown increment of the minute segment (default: 1)                                                                          |
| `monthAriaLabel`     | string                | ARIA label for the month segment input. Defaults to `Month`                                                                                 |
| `yearAriaLabel`      | string                | ARIA label for the year segment input. Defaults to `Year`                                                                                   |

### Hint

<Aside>A `label` is required for the `hint` to be displayed.</Aside>

Use the property `hint` to add a description or validation instructions.


```ts title="datetimeinput.ts"

export default [
  gui.inputs.dateTimeInput('meetingAt', {
    hint: 'Please enter the meeting date and start time',
    label: 'Meeting At',
  }),
];
```

_Live demo on the docs page. Form definition: [datetimeinput-hint.ts](https://golemui.com/template/widgets-dx/datetimeinput/datetimeinput-hint.ts)._

### Icon

Use the property `icon` to add an icon to the widget. The value of `icon` represents a set of CSS classes separated by spaces. The icon is displayed inside the input border.


```ts title="datetimeinput.ts"

export default [
  gui.inputs.dateTimeInput('meetingAt', {
    icon: 'calendar_month',
    label: 'Meeting At',
  }),
];
```

_Live demo on the docs page. Form definition: [datetimeinput-icon.ts](https://golemui.com/template/widgets-dx/datetimeinput/datetimeinput-icon.ts)._

### Hour Format

By default the 12-hour/24-hour layout comes from the locale's hour cycle. Use the property `hourFormat` (`'12'` or `'24'`) to force one of them.


```ts title="datetimeinput.ts"

export default [
  gui.inputs.dateTimeInput('meetingAt12', {
    hourFormat: '12',
    label: 'Meeting At (12h)',
  }),
  gui.inputs.dateTimeInput('meetingAt24', {
    hourFormat: '24',
    label: 'Meeting At (24h)',
  }),
];
```

_Live demo on the docs page. Form definition: [datetimeinput-hourformat.ts](https://golemui.com/template/widgets-dx/datetimeinput/datetimeinput-hourformat.ts)._

### Minute Step

Use the property `minuteStep` to control the ArrowUp/ArrowDown increment of the minute segment, useful for appointment-style forms where times snap to a grid (e.g. every 15 minutes). Typing a value is not restricted by the step. The default is `1`.


```ts title="datetimeinput.ts"

export default [
  gui.inputs.dateTimeInput('meetingAt', {
    minuteStep: 15,
    label: 'Meeting At',
  }),
];
```

_Live demo on the docs page. Form definition: [datetimeinput-minutestep.ts](https://golemui.com/template/widgets-dx/datetimeinput/datetimeinput-minutestep.ts)._

### Min and Max Boundaries

Use `minDate` / `maxDate` (ISO dates) and `minTime` / `maxTime` (ISO times), all inclusive, to specify the boundaries for accepted values. A completed value outside a boundary raises an input error instead of a value; customize (and localize) the messages with `minDateMessage`, `maxDateMessage`, `minTimeMessage` and `maxTimeMessage`.


```ts title="datetimeinput.ts"

export default [
  gui.inputs.dateTimeInput('meetingAt', {
    hint: 'Meetings between 2026-02-01 and 2026-07-31, office hours 9:00 to 18:00',
    minDate: '2026-02-01',
    maxDate: '2026-07-31',
    minTime: '09:00:00',
    maxTime: '18:00:00',
    minDateMessage: 'No meetings before February 2026',
    maxDateMessage: 'No meetings after July 2026',
    minTimeMessage: 'Office not open until 9:00',
    maxTimeMessage: 'Office closed from 18:00',
    label: 'Meeting At',
  }),
];
```

_Live demo on the docs page. Form definition: [datetimeinput-minmax.ts](https://golemui.com/template/widgets-dx/datetimeinput/datetimeinput-minmax.ts)._

### Invalid Date

Use the property `invalidDateMessage` to customize (and localize) the error shown when the completed date segments don't form a real calendar date, such as February 30 or the 13th month.


```ts title="datetimeinput.ts"

export default [
  gui.inputs.dateTimeInput('meetingAt', {
    hint: 'Type a date that doesn\'t exist, e.g. February 30',
    invalidDateMessage: 'Please enter a real calendar date',
    label: 'Meeting At',
  }),
];
```

_Live demo on the docs page. Form definition: [datetimeinput-invaliddate.ts](https://golemui.com/template/widgets-dx/datetimeinput/datetimeinput-invaliddate.ts)._

## Styling

Date Time Inputs can be styled as explained in the [Styling Guide](https://golemui.com/dx/styling/overview.md).

### CSS Variables

Following you will find a list with the CSS Variables and a quick description of what you will style.

| CSS Variable               | Description                                                            |
| -------------------------- | ---------------------------------------------------------------------- |
| `--gui-text-default`       | Text color and active piece (date/time segment) visual underline color |
| `--gui-intent-error`       | Border color when invalid                                              |
| `--gui-border-focus`       | Border color when a segment is focused                                 |
| `--gui-shadow-focus`       | Focus shadow                                                           |
| `--gui-shadow-focus-error` | Focus shadow when invalid                                              |

### Anatomy

This is the anatomy of the Date Time Input Widget in case you want to use your CSS styles.


```html title="datetimeinput-anatomy.html"
<gui-date-time-input class="gui-date-time gui-field">
  <gui-date-time class="gui-date-time--icon gui-field">
    <span class="gui-label" id="fieldUid_label">
      <span class="gui-label__text">Label</span>
      <div class="gui-widget-hint" id="fieldUid_hint" aria-hidden="true">Hint</div>
    </span>

    <div class="gui-widget">
      <div
        role="group"
        id="fieldUid"
        class="gui-widget-input gui-parts gui-parts-ring gui-date-time-input gui-calendar--icon"
        aria-labelledby="fieldUid_label"
        aria-describedby="fieldUid_hint"
      >
        <div class="gui-parts__touch-target gui-date-time-input__touch-target">
          <input
            type="text"
            inputmode="numeric"
            role="spinbutton"
            autocomplete="off"
            class="gui-parts__part gui-date-time-input__part"
            data-type="month"
            maxlength="2"
            placeholder="mm"
            tabindex="0"
            aria-label="Month"
            aria-valuemin="1"
            aria-valuemax="12"
            aria-valuenow="7"
          />
          <div class="gui-parts__visual-underline gui-date-time-input__visual-underline"></div>
        </div>
        <span class="gui-date-time-input__separator">/</span>
        <div class="gui-parts__touch-target gui-date-time-input__touch-target">
          <input
            type="text"
            inputmode="numeric"
            role="spinbutton"
            autocomplete="off"
            class="gui-parts__part gui-date-time-input__part"
            data-type="day"
            maxlength="2"
            placeholder="dd"
            tabindex="-1"
            aria-label="Day"
            aria-valuemin="1"
            aria-valuemax="31"
            aria-valuenow="4"
          />
          <div class="gui-parts__visual-underline gui-date-time-input__visual-underline"></div>
        </div>
        <span class="gui-date-time-input__separator">/</span>
        <div class="gui-parts__touch-target gui-date-time-input__touch-target">
          <input
            type="text"
            inputmode="numeric"
            role="spinbutton"
            autocomplete="off"
            class="gui-parts__part gui-date-time-input__part gui-parts__year gui-date-time-input__year"
            data-type="year"
            maxlength="4"
            placeholder="yyyy"
            tabindex="-1"
            aria-label="Year"
            aria-valuemin="1900"
            aria-valuemax="9999"
            aria-valuenow="2026"
          />
          <div class="gui-parts__visual-underline gui-date-time-input__visual-underline"></div>
        </div>
        <span class="gui-date-time-input__separator">,</span>
        <div dir="ltr" class="gui-parts__time-cluster gui-date-time-input__time-cluster">
          <div class="gui-parts__touch-target gui-date-time-input__touch-target">
            <input
              type="text"
              inputmode="numeric"
              role="spinbutton"
              autocomplete="off"
              class="gui-parts__part gui-date-time-input__part"
              data-type="hour"
              maxlength="2"
              placeholder="hh"
              tabindex="-1"
              aria-label="Hour"
              aria-valuemin="1"
              aria-valuemax="12"
              aria-valuenow="9"
            />
            <div class="gui-parts__visual-underline gui-date-time-input__visual-underline"></div>
          </div>
          <span class="gui-date-time-input__separator">:</span>
          <div class="gui-parts__touch-target gui-date-time-input__touch-target">
            <input
              type="text"
              inputmode="numeric"
              role="spinbutton"
              autocomplete="off"
              class="gui-parts__part gui-date-time-input__part"
              data-type="minute"
              maxlength="2"
              placeholder="mm"
              tabindex="-1"
              aria-label="Minute"
              aria-valuemin="0"
              aria-valuemax="59"
              aria-valuenow="30"
            />
            <div class="gui-parts__visual-underline gui-date-time-input__visual-underline"></div>
          </div>
        </div>
        <span class="gui-date-time-input__separator"></span>
        <div class="gui-parts__touch-target gui-date-time-input__touch-target">
          <button
            type="button"
            class="gui-parts__part gui-parts__dayperiod gui-date-time-input__part gui-date-time-input__dayperiod"
            data-type="dayPeriod"
            tabindex="-1"
            aria-label="AM/PM"
          >
            AM
          </button>
          <div class="gui-parts__visual-underline gui-date-time-input__visual-underline"></div>
        </div>
      </div>
      <span
        aria-hidden="true"
        class="gui-widget-icon calendar_month"
        data-icon="calendar_month"
      ></span>
    </div>
  </gui-date-time>
</gui-date-time-input>
```
