# Date Input

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

Date Input widgets are [Input Fields](https://golemui.com/dx/widgets-reference/input-fields/overview.md) that provide a structured, segmented text-input approach to manual date entry, offering a keyboard-friendly alternative to interactive calendars. The date segments automatically localize based on the user's region and locale.


```ts title="dateinput.ts"

export default [
  gui.inputs.dateInput('birthDate', {
    label: 'Birth Date',
  }),
];
```

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

## Props

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

| prop                 | type                  | description                                                                                                                            |
| -------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `dayAriaLabel`       | string                | ARIA label for the day segment input. Defaults to `Day`                                                                                |
| `hint`               | string                | A description to display below the segmented inputs                                                                                    |
| `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 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`                                                                           |
| `minDate`            | string                | Earliest allowed date (ISO date, inclusive)                                                                                            |
| `minDateMessage`     | string \| Localizable | Error message shown when the entered date is before `minDate`                                                                          |
| `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="dateinput.ts"

export default [
  gui.inputs.dateInput('birthDate', {
    hint: 'Please enter your date of birth',
    label: 'Birth Date',
  }),
];
```

_Live demo on the docs page. Form definition: [dateinput-hint.ts](https://golemui.com/template/widgets-dx/dateinput/dateinput-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="dateinput.ts"

export default [
  gui.inputs.dateInput('birthDate', {
    icon: 'calendar_month',
    label: 'Birth Date',
  }),
];
```

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

### Min and Max Dates

Use the properties `minDate` and `maxDate` (ISO dates, both inclusive) to specify the boundaries for accepted dates. A completed date outside the boundaries raises an input error instead of a value; customize (and localize) the messages with `minDateMessage` and `maxDateMessage`.


```ts title="dateinput.ts"

export default [
  gui.inputs.dateInput('appointmentDate', {
    hint: 'Appointments available between 2026-02-01 and 2026-07-31',
    minDate: '2026-02-01',
    maxDate: '2026-07-31',
    minDateMessage: 'No appointments before February 2026',
    maxDateMessage: 'No appointments after July 2026',
    label: 'Appointment Date',
  }),
];
```

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

### Invalid Date

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


```ts title="dateinput.ts"

export default [
  gui.inputs.dateInput('birthDate', {
    hint: 'Try a date that doesn\'t exist, e.g. February 30',
    invalidDateMessage: 'Please enter a real calendar date',
    label: 'Birth Date',
  }),
];
```

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

## Styling

Date 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-intent-error` | Border and focus shadow color when invalid                                     |
| `--gui-text-default` | Active piece (day/month/year) visual underline color and standard focus shadow |

### Anatomy

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


```html title="dateinput-anatomy.html"
<gui-date-input class="gui-date gui-field">
  <gui-date class="gui-date--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-input gui-calendar--icon"
        aria-labelledby="fieldUid_label"
        aria-describedby="fieldUid_hint"
      >
        <div class="gui-parts__touch-target gui-date-input__touch-target">
          <input
            type="text"
            inputmode="numeric"
            role="spinbutton"
            autocomplete="off"
            class="gui-parts__part gui-date-input__part"
            data-type="month"
            maxlength="2"
            placeholder="mm"
            tabindex="0"
            aria-label="Month"
            aria-valuemin="1"
            aria-valuemax="12"
            aria-valuenow="12"
          />
          <div class="gui-parts__visual-underline gui-date-input__visual-underline"></div>
        </div>
        <span class="gui-date-input__separator">/</span>
        <div class="gui-parts__touch-target gui-date-input__touch-target">
          <input
            type="text"
            inputmode="numeric"
            role="spinbutton"
            autocomplete="off"
            class="gui-parts__part gui-date-input__part"
            data-type="day"
            maxlength="2"
            placeholder="dd"
            tabindex="-1"
            aria-label="Day"
            aria-valuemin="1"
            aria-valuemax="31"
            aria-valuenow="25"
          />
          <div class="gui-parts__visual-underline gui-date-input__visual-underline"></div>
        </div>
        <span class="gui-date-input__separator">/</span>
        <div class="gui-parts__touch-target gui-date-input__touch-target">
          <input
            type="text"
            inputmode="numeric"
            role="spinbutton"
            autocomplete="off"
            class="gui-parts__part gui-date-input__part gui-parts__year gui-date-input__year"
            data-type="year"
            maxlength="4"
            placeholder="yyyy"
            tabindex="-1"
            aria-label="Year"
            aria-valuemin="1900"
            aria-valuemax="9999"
            aria-valuenow="2024"
          />
          <div class="gui-parts__visual-underline gui-date-input__visual-underline"></div>
        </div>
      </div>
      <span
        aria-hidden="true"
        class="gui-widget-icon calendar_month"
        data-icon="calendar_month"
      ></span>
    </div>
  </gui-date>
</gui-date-input>
```
