Component v1.1.0 Forms

Date Picker

Localized calendar-grid date selection with ISO Angular Forms values, date constraints, and full keyboard navigation.

API Stable 2.1 WCAG notes Ready Dark mode
Selector
ui-date-picker
Package
@ngnova/ui/date-picker

Import

Standalone Tailwind v4
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.

API Reference

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.

Angular template ui-date-picker-recipe.example.html
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.

Angular template ui-date-picker-recipe.example.html
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.

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.

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.