DateInput

Choose dates and local times without turning a calendar value into a UTC instant.

Category: Forms and selection
Import: @neural-ui/core/date-input
Selector: neu-date-input

import { NeuDateInputControl } from '@neural-ui/core/date-input';

Choose a date

Use DateInput for a delivery date, appointment time or date range. Import the component and keep the value in a signal; no date adapter or icon package is required. Click anywhere in the field to open the picker, or use the chevron button.

A CivilDate describes a day on the calendar, not an instant. civilDate('2026-10-15') validates that value without adding a timezone. Keep it as a civil value when sending it to your application; convert to an instant only when your business rules explicitly supply a time and timezone.

Delivery date

Civil value: 2026-10-15

Configurator

Explore the seven value modes, overlay or inline presentation, size and calendar options. Changing mode resets the demo value to the matching public type; the generated template reflects your settings.

Live preview

Delivery date

Current application value

Calendar view event

Advanced options · 13

Generated template. The Code tab includes imports and state.

<neu-date-input
  [(value)]="value"
  (viewChange)="lastViewChange.set($event)"
  label="Delivery date"
  mode="date"
  presentation="overlay"
  size="md"
  [floatingLabel]="true"
  [firstDayOfWeek]="1"
  [showWeekNumbers]="false"
  [showMonthYearPicker]="true"
  [locale]="'en'"
/>

State and data for this configuration

These values match the current preview. Complete handlers, Core imports and templates are in Source.

import { signal } from '@angular/core';

export const value = signal("2026-10-15");

Data, callback and structured configuration inputs

These inputs require a model or function, not a checkbox. Edit the same-named field in the Source component and bind it in the template; data already used by this preview appears in the state above.

disabledDates · readonly CivilDate[] | ((date: CivilDate) => boolean)

In Source: define disabledDates with this type and use [disabledDates]="disabledDates" (or disabledDates() for a signal).

errors · readonly ValidationError.WithOptionalFieldTree[]

In Source: define errors with this type and use [errors]="errors" (or errors() for a signal).

max · NonNullable<V> | undefined

In Source: define max with this type and use [max]="max" (or max() for a signal).

min · NonNullable<V> | undefined

In Source: define min with this type and use [min]="min" (or min() for a signal).

presets · readonly NeuDatePreset[]

In Source: define presets with this type and use [presets]="presets" (or presets() for a signal).

Modes and value types

Choose the mode for the value you need to store. date uses CivilDate (2026-10-15); time uses LocalTime (09:30); datetime uses LocalDateTime (2026-10-15T09:30). None represents a UTC instant.

Use multiple for independent days (readonly CivilDate[]). Use range for an interval (CivilDateRange with start and end); a partially selected range can have a null endpoint. month uses CivilMonth and year uses CivilYear when day precision is unnecessary. Each example below owns a separate, correctly typed value.

Date

"2026-10-15"

Local time

"09:30"

Local date and time

"2026-10-15T09:30"

Multiple dates

[ "2026-10-15", "2026-10-20" ]

Date range

{ "start": "2026-10-15", "end": "2026-10-20" }

Month

{ "year": 2026, "month": 10 }

Year

{ "year": 2026 }

Limits and presentation

This delivery window allows October 10–20, 2026, except October 17. min and max bound the civil date; disabledDates excludes a specific day. Try typing an out-of-range date and opening the calendar to compare both entry paths.

The switches explore disabled, readonly and inline presentation without exposing unrelated object APIs. Keep mode-specific values typed; changing a mode in a real form may require changing or clearing its model.

Disabled

Readonly

Inline calendar

Delivery date

Civil value: 2026-10-15

Validation with Signal Forms

Bind FormField to a typed field. The schema supplies required validation, disabled and readonly state; you do not need a second value binding. Blur the empty field to display its error. Reset clears the value and form interaction state.

Use min, max and disabledDates for selectable-date restrictions. Keep application validation in the form schema and provide a message explaining how to correct invalid input.

Required delivery date

Disabled

Readonly

Date: — · Valid: false

Value and events

value is a two-way model: [(value)] synchronizes the selected civil value with your signal. In a Signal Forms form, FormField performs that connection. Do not combine both bindings on the same control.

opened and closed describe the overlay lifecycle. cleared reports the clear action and touch reports field interaction. viewChange reports the calendar view; it is not a selected-date change. Use valueChange when your application needs the new value.

Accessibility and keyboard

Core manages the calendar grid, keyboard movement and overlay focus. Your application must provide a meaningful label and validation message, and associate any additional help through ariaDescribedBy. A placeholder does not replace a label.

Disabled fields cannot be edited; readonly fields retain their value without allowing changes. Test the complete form with your content and assistive technology, especially error announcements and overlay return focus.

Key	Action
`ArrowDown`	Open a date calendar from the field.
`ArrowLeft / ArrowRight / ArrowUp / ArrowDown`	Move one day horizontally or one week vertically in the day grid.
`Home / End`	Move to the start or end of the calendar week.
`PageUp / PageDown`	Move to the previous or next month in the day grid.
`Enter / Space`	Choose the focused calendar value.
`Escape`	Close the overlay.

API

The public NeuDateInputComponent export aliases NeuDateInputControl. Configure the control with inputs, connect its value model, and listen to outputs when you need interaction notifications. There are no public template directives or consumer imperative methods for this control.

Inputs

Configure the component with [property]="value". Your application supplies these values; the component does not replace the state you pass in.

Name	Type	Default	Template binding	Description
`ariaDescribedBy`	`string`	`''`	`[ariaDescribedBy]`	Space-separated ids of additional descriptive elements.
`ariaLabel`	`string`	`''`	`[ariaLabel]`	Accessible name when an appropriate visible label is unavailable.
`dateFormat`	`"short" \| "medium" \| "long" \| "full" \| "numeric"`	`'short'`	`[dateFormat]`	Display format for the date, independent of the stored typed value.
`dirty`	`boolean`	`false`	`[dirty]`	Tracks whether the form value has been edited.
`disabled`	`boolean`	`false`	`[disabled]`	Prevents interaction; supplied by FormField when bound to Signal Forms.
`disabledDates`	`readonly CivilDate[] \| ((date: CivilDate) => boolean)`	`[]`	`[disabledDates]`	Array of civil days or predicate identifying dates that cannot be selected.
`errorMessage`	`string`	`''`	`[errorMessage]`	Human-readable correction message for the invalid state.
`errors`	`readonly ValidationError.WithOptionalFieldTree[]`	`[]`	`[errors]`	Structured Signal Forms validation errors.
`firstDayOfWeek`	`number`	`1`	`[firstDayOfWeek]`	First weekday in the calendar: 0 is Sunday, 1 is Monday.
`floatingLabel`	`boolean`	`false`	`[floatingLabel]`	Float the visible label inside the field border.
`hidden`	`boolean`	`false`	`[hidden]`	Hides the control through the form state contract.
`hint`	`string`	`''`	`[hint]`	Supporting text below the field.
`inputId`	`string`	`''`	`[inputId]`	Explicit input id for label and external help associations.
`invalid`	`boolean`	`false`	`[invalid]`	Displays the invalid state supplied by the form or application.
`label`	`string`	`''`	`[label]`	Visible field label associated with its input.
`locale`	`string \| null`	`null`	`[locale]`	Locale used to format display text; it does not convert the civil model into an instant.
`max`	`NonNullable<V> \| undefined`	`undefined`	`[max]`	Upper permitted boundary. Supply a civil value compatible with the selected mode.
`min`	`NonNullable<V> \| undefined`	`undefined`	`[min]`	Lower permitted boundary. Supply a civil value compatible with the selected mode.
`mode`	`NeuDateMode`	`'date'`	`[mode]`	Value and picker mode: date, time, datetime, multiple, range, month or year.
`name`	`string`	`''`	`[name]`	Native form control name.
`pending`	`boolean`	`false`	`[pending]`	Indicates that form validation is pending.
`placeholder`	`string`	`''`	`[placeholder]`	Short format hint while empty; not a replacement for label.
`presentation`	`NeuDatePresentation`	`'overlay'`	`[presentation]`	Display the calendar in an overlay or inline in the page.
`presets`	`readonly NeuDatePreset[]`	`[]`	`[presets]`	Named preset ranges offered by the range calendar; see NeuDatePreset.
`readonly`	`boolean`	`false`	`[readonly]`	Keeps the value readable without allowing changes.
`required`	`boolean`	`false`	`[required]`	Marks the field as required; define validation in your form schema.
`showMonthYearPicker`	`boolean`	`false`	`[showMonthYearPicker]`	Allow switching calendar month and year through the header chooser.
`showWeekNumbers`	`boolean`	`false`	`[showWeekNumbers]`	Display week numbers next to the calendar rows.
`size`	`"sm" \| "md" \| "lg"`	`'md'`	`[size]`	Field size: sm, md or lg.
`step`	`number`	`1`	`[step]`	Minute increment for time editing.
`touched`	`boolean`	`false`	`[touched]`	Field interaction state supplied by Signal Forms or your application.
`yearRange`	`number`	`12`	`[yearRange]`	Number of years shown by the year chooser.

Models

A model supports [(property)]="signal" or the [property] and (propertyChange) pair. Choose one form, not both.

Name	Type	Default	Template binding	Description
`value`	`V`	`null as V`Derived default	`[(value)]`	Editable civil value. Match its type to mode; use FormField or [(value)], not both.

Outputs

Listen to an event with (event)="handler($event)". The table explains the data your handler receives and how to use it.

Name	Payload	Template binding	Description
`cleared`	`void`	`(cleared)="onCleared($event)"`	Reports the clear action; the value model carries the resulting value.
`closed`	`void`	`(closed)="onClosed($event)"`	Emits when the overlay closes.
`opened`	`void`	`(opened)="onOpened($event)"`	Emits when the overlay opens.
`touch`	`void`	`(touch)="onTouch($event)"`	Notifies the form that the control was touched; no value payload.
`viewChange`	`NeuDateViewChangeEvent`	`(viewChange)="onViewChange($event)"`	Reports a calendar view change, not a committed value change.

Templates

ng-content projects content into the component. TemplateRef inputs receive a template; ng-template directives identify templates with a typed context. A directive shared by an entrypoint is not necessarily a slot of this component.

This component does not expose content projection or public customization templates.

Public Types

Open a type to inspect its definition and interface fields.

CivilDateTypeScript

import type { CivilDate } from '@neural-ui/core/date-input';

// Public declaration (reference only)
export type CivilDate = string & {
    readonly [civilDateBrand]: true;
};

CivilDateRangeTypeScript

import type { CivilDate } from '@neural-ui/core/date-input';

import type { CivilDateRange } from '@neural-ui/core/date-input';

// Public declaration (reference only)
export interface CivilDateRange {
  readonly end: CivilDate | null;
  readonly start: CivilDate | null;
}

CivilMonthTypeScript

import type { CivilMonth } from '@neural-ui/core/date-input';

// Public declaration (reference only)
export interface CivilMonth {
  readonly month: number;
  readonly year: number;
}

CivilYearTypeScript

LocalDateTimeTypeScript

import type { LocalDateTime } from '@neural-ui/core/date-input';

// Public declaration (reference only)
export type LocalDateTime = string & {
    readonly [localDateTimeBrand]: true;
};

LocalTimeTypeScript

import type { LocalTime } from '@neural-ui/core/date-input';

// Public declaration (reference only)
export type LocalTime = string & {
    readonly [localTimeBrand]: true;
};

NeuDateBoundaryTypeScript

import type { CivilDate } from '@neural-ui/core/date-input';
import type { CivilMonth } from '@neural-ui/core/date-input';
import type { CivilYear } from '@neural-ui/core/date-input';
import type { LocalDateTime } from '@neural-ui/core/date-input';
import type { LocalTime } from '@neural-ui/core/date-input';
import type { NeuDateMode } from '@neural-ui/core/date-input';

import type { NeuDateBoundary } from '@neural-ui/core/date-input';

// Public declaration (reference only)
export type NeuDateBoundary<M extends NeuDateMode> = M extends 'time' ? LocalTime : M extends 'datetime' ? LocalDateTime : M extends 'month' ? CivilMonth : M extends 'year' ? CivilYear : CivilDate;

NeuDateInputComponentTypeScript

import type { NeuDateMode } from '@neural-ui/core/date-input';
import type { NeuDateValue } from '@neural-ui/core/date-input';

import type { NeuDateInputComponent } from '@neural-ui/core/date-input';

// Public declaration (reference only)
export type NeuDateInputComponent<M extends NeuDateMode = 'date'> = NeuDateInputControl<NeuDateValue<M>>;
const NeuDateInputComponent: typeof NeuDateInputControl;

NeuDateModeTypeScript

import type { NeuDateMode } from '@neural-ui/core/date-input';

// Public declaration (reference only)
export type NeuDateMode = 'date' | 'time' | 'datetime' | 'multiple' | 'range' | 'month' | 'year';

NeuDatePresentationTypeScript

import type { NeuDatePresentation } from '@neural-ui/core/date-input';

// Public declaration (reference only)
export type NeuDatePresentation = 'overlay' | 'inline';

NeuDatePresetTypeScript

import type { CivilDateRange } from '@neural-ui/core/date-input';

import type { NeuDatePreset } from '@neural-ui/core/date-input';

// Public declaration (reference only)
interface NeuDatePreset {
  readonly label: string;
  readonly range: CivilDateRange | (() => CivilDateRange);
}

NeuDateValueTypeScript

import type { NeuDateMode } from '@neural-ui/core/date-input';
import type { NeuDateValueMap } from '@neural-ui/core/date-input';

import type { NeuDateValue } from '@neural-ui/core/date-input';

// Public declaration (reference only)
export type NeuDateValue<M extends NeuDateMode> = NeuDateValueMap[M];

NeuDateValueMapTypeScript

import type { CivilDate } from '@neural-ui/core/date-input';
import type { CivilDateRange } from '@neural-ui/core/date-input';
import type { CivilMonth } from '@neural-ui/core/date-input';
import type { CivilYear } from '@neural-ui/core/date-input';
import type { LocalDateTime } from '@neural-ui/core/date-input';
import type { LocalTime } from '@neural-ui/core/date-input';

import type { NeuDateValueMap } from '@neural-ui/core/date-input';

// Public declaration (reference only)
export interface NeuDateValueMap {
  readonly date: CivilDate | null;
  readonly datetime: LocalDateTime | null;
  readonly month: CivilMonth | null;
  readonly multiple: readonly CivilDate[];
  readonly range: CivilDateRange;
  readonly time: LocalTime | null;
  readonly year: CivilYear | null;
}

NeuDateViewChangeEventTypeScript

import type { CivilDate } from '@neural-ui/core/date-input';

import type { NeuDateViewChangeEvent } from '@neural-ui/core/date-input';

// Public declaration (reference only)
interface NeuDateViewChangeEvent {
  readonly end: CivilDate;
  readonly start: CivilDate;
}

Theming

DateInput uses shared field, surface, text and focus roles rather than a separate date-only palette. This local wrapper changes border, surface and text for one field; the adjacent field keeps the inherited theme.

A shared token also affects other Neural controls inside the same wrapper. Keep overrides scoped, preserve readable text and focus contrast, and inspect the calendar overlay as well as the closed field.

Inherited theme

Original date

Local override

Customized date

Specific tokens

This component uses shared theme tokens rather than dedicated component hooks.

Shared tokens used

Override these on a local wrapper to affect this example. An override on :root affects other components that use the same token.

Token	Purpose here	Other impact	Default / fallback
`--neu-border`	Normal control and cell borders	Shared by other Core consumers; scope the override.	`rgba(15, 23, 42, 0.08)`
`--neu-border-hover`	Control borders on hover	Shared by other Core consumers; scope the override.	`rgba(15, 23, 42, 0.16)`
`--neu-error`	Invalid field or danger-action color	Shared by other Core consumers; scope the override.	`#dc2626`
`--neu-error-text`	Error text and danger outline/ghost Button text in both themes	Shared by other Core consumers; scope the override.	`#991b1b`
`--neu-focus-ring`	Normal keyboard-focus ring	Shared by other Core consumers; scope the override.	`0 0 0 var(--neu-focus-ring-width) rgba(0, 122, 255, 0.15)`
`--neu-primary`	Brand color for active controls and emphasis	Shared by other Core consumers; scope the override.	`#007aff`
`--neu-primary-dark`	Dark brand shade; outline and ghost Button text in the light theme	Shared by other Core consumers; scope the override.	`#005fcc`
`--neu-primary-fg`	Foreground drawn over the primary background	Shared by other Core consumers; scope the override.	`#ffffff`