Date Picker
Localized calendar-grid date selection with ISO Angular Forms values, date constraints, and full keyboard navigation.
- Selector
- ui-date-picker
- Package
- @ngnova/ui/date-picker
Import
import { UiDatePickerComponent } from '@ngnova/ui/date-picker';Usage & variants
Live examples use the public ui-date-picker API, paired with the exact snippet a product team would paste into an Angular app.
Release date
Localized calendar-grid date selection with ISO Angular Forms values, date constraints, and full keyboard navigation.
Choose a publication date.
Production guidance
Use these notes to decide when the component belongs in a product workflow and what to verify before shipping.
When to use
Use when users benefit from calendar context, date constraints, or keyboard exploration.
Watch for
Invalid external values render empty instead of guessing a date format.
Product recipes
Apply Date Picker in distinct, copyable product scenarios—not just an isolated component state.
Bounded release date
The form owns the ISO value while the component localizes all visible labels.
1 2 3 4 5 6 7 8
<ui-date-picker
label="Release date"
[formControl]="releaseDate"
min="2026-01-01"
max="2027-12-31"
[disabledDates]="releaseBlackouts"
clearable
/>Monday-first localized calendar
Locale and week start are independent so regional product policy stays explicit.
1 2 3 4 5 6
<ui-date-picker
label="Invoice date"
locale="en-GB"
[firstDayOfWeek]="1"
[formControl]="invoiceDate"
/>API Reference
Inputs and outputs are semver-sensitive public API. Keep examples aligned with this table.
Inputs
label '' string Visible native label for the readonly date display input.
placeholder 'Select a date' string Text shown while no ISO date is selected.
helperText '' string Supporting text described by the trigger input.
errorText '' string Validation message that marks the trigger input invalid.
inputId generated string Stable base ID for label, calendar, and message relationships.
name '' string Native form control name.
ariaLabel '' string Accessible trigger name used when no visible label is supplied.
locale 'en-US' string Intl locale for selected, month, weekday, and full-date labels.
size 'md' 'sm' | 'md' | 'lg' Trigger frame height, spacing, and type scale.
min '' string Inclusive minimum ISO date in YYYY-MM-DD format.
max '' string Inclusive maximum ISO date in YYYY-MM-DD format.
startAt '' string Initial ISO calendar date when no value is selected.
disabledDates [] readonly string[] Specific ISO dates excluded from pointer and keyboard selection.
open false boolean Controlled calendar state with internal interaction fallback.
disabled false boolean Disables trigger, clear, calendar, and date interaction.
required false boolean Shows the required indicator and exposes aria-required.
clearable false boolean Shows a localized clear action for selected values.
showOutsideDays true boolean Shows adjacent-month dates while retaining the stable six-week grid.
closeOnSelect true boolean Closes and restores trigger focus after date selection.
firstDayOfWeek 0 number First weekday index from Sunday 0 through Saturday 6.
calendarAriaLabel 'Choose date' string Localized accessible name for the non-modal calendar dialog.
openAriaLabel 'Open calendar' string Localized accessible name for the closed calendar toggle.
closeAriaLabel 'Close calendar' string Localized accessible name for the open calendar toggle.
clearAriaLabel 'Clear date' string Localized accessible name for the clear action.
previousMonthAriaLabel 'Previous month' string Localized accessible name for previous-month navigation.
nextMonthAriaLabel 'Next month' string Localized accessible name for next-month navigation.
todayText 'Today' string Localized label for the today shortcut.
| Name | Type | Default | Description |
|---|---|---|---|
label | string | '' | Visible native label for the readonly date display input. |
placeholder | string | 'Select a date' | Text shown while no ISO date is selected. |
helperText | string | '' | Supporting text described by the trigger input. |
errorText | string | '' | Validation message that marks the trigger input invalid. |
inputId | string | generated | Stable base ID for label, calendar, and message relationships. |
name | string | '' | Native form control name. |
ariaLabel | string | '' | Accessible trigger name used when no visible label is supplied. |
locale | string | 'en-US' | Intl locale for selected, month, weekday, and full-date labels. |
size | 'sm' | 'md' | 'lg' | 'md' | Trigger frame height, spacing, and type scale. |
min | string | '' | Inclusive minimum ISO date in YYYY-MM-DD format. |
max | string | '' | Inclusive maximum ISO date in YYYY-MM-DD format. |
startAt | string | '' | Initial ISO calendar date when no value is selected. |
disabledDates | readonly string[] | [] | Specific ISO dates excluded from pointer and keyboard selection. |
open | boolean | false | Controlled calendar state with internal interaction fallback. |
disabled | boolean | false | Disables trigger, clear, calendar, and date interaction. |
required | boolean | false | Shows the required indicator and exposes aria-required. |
clearable | boolean | false | Shows a localized clear action for selected values. |
showOutsideDays | boolean | true | Shows adjacent-month dates while retaining the stable six-week grid. |
closeOnSelect | boolean | true | Closes and restores trigger focus after date selection. |
firstDayOfWeek | number | 0 | First weekday index from Sunday 0 through Saturday 6. |
calendarAriaLabel | string | 'Choose date' | Localized accessible name for the non-modal calendar dialog. |
openAriaLabel | string | 'Open calendar' | Localized accessible name for the closed calendar toggle. |
closeAriaLabel | string | 'Close calendar' | Localized accessible name for the open calendar toggle. |
clearAriaLabel | string | 'Clear date' | Localized accessible name for the clear action. |
previousMonthAriaLabel | string | 'Previous month' | Localized accessible name for previous-month navigation. |
nextMonthAriaLabel | string | 'Next month' | Localized accessible name for next-month navigation. |
todayText | string | 'Today' | Localized label for the today shortcut. |
Outputs
valueChange OutputEmitterRef<string> Emits a selected ISO date or an empty value when cleared.
openChange OutputEmitterRef<boolean> Emits interaction-requested calendar state.
dateSelected OutputEmitterRef<UiDatePickerSelection> Emits the ISO value and an equivalent UTC-safe Date.
monthChange OutputEmitterRef<string> Emits the visible month as its first ISO date.
focused OutputEmitterRef<FocusEvent> Emits trigger input focus without colliding with the native event name.
blurred OutputEmitterRef<FocusEvent> Emits when focus leaves the complete Date Picker.
| Name | Type | Description |
|---|---|---|
valueChange | OutputEmitterRef<string> | Emits a selected ISO date or an empty value when cleared. |
openChange | OutputEmitterRef<boolean> | Emits interaction-requested calendar state. |
dateSelected | OutputEmitterRef<UiDatePickerSelection> | Emits the ISO value and an equivalent UTC-safe Date. |
monthChange | OutputEmitterRef<string> | Emits the visible month as its first ISO date. |
focused | OutputEmitterRef<FocusEvent> | Emits trigger input focus without colliding with the native event name. |
blurred | OutputEmitterRef<FocusEvent> | Emits when focus leaves the complete Date Picker. |
Accessibility
- The readonly trigger exposes dialog popup state and stable controls, description, required, and invalid relationships.
- The named dialog contains a labelled grid, localized column headers, full-date day names, selected/current states, and native disabled controls.
- Only the active day is tabbable; month changes are announced politely and selecting or escaping restores trigger focus.
Keyboard behavior
- Arrow keys move by day or week while skipping disabled dates; Home and End move within the active week.
- Page Up and Page Down move by month, Shift modifies them to years, and Enter or Space selects.
- Escape closes and restores trigger focus; Tab follows the dialog controls without trapping focus.
Testing guidance
- Use UiDatePickerHarness to read display/month state, open/close, enumerate visible dates, navigate months, select or clear, and inspect date/field disabled state.
- Test ISO form integration, locale/week start, leap years, month boundaries, min/max, blackouts, all keyboard commands, clearing, today, outside days, focus return, and localization.