Datepicker

The <nys-datepicker> component lets users select a single date by typing into the input field or choosing from a calendar popup. On Safari and mobile devices, it falls back to the native date picker.

Accessibility

The <nys-datepicker> component includes the following accessibility features:

• Built on a native <input type="date">, so screen readers announce the field correctly

• The calendar button has aria-haspopup="dialog" and aria-expanded to communicate popup state

• The calendar popup uses role="dialog" with aria-modal and traps focus when open

• Press Space on the input to open the calendar; press Escape to close it and return focus to the input

• Tab and Shift+Tab cycle through focusable elements inside the calendar without escaping

• When required is set, aria-required="true" is applied and validation fires on blur

• Error messages are rendered via <nys-errormessage> and associated with the input for assistive technology

  Additional accessibility test and build content is coming soon, in a new format.

Options

Value and form output

The value prop accepts a Date object or an ISO date string (YYYY-MM-DD). The input displays the date in MM/DD/YYYY format. Internally, the component stores and submits the value as a string in ISO format (YYYY-MM-DD).

Valid value examples

// Using a Date object (month is 0-indexed)
datepicker.value = new Date(2025, 5, 1); // June 1, 2025
// Using an ISO string (recommended)
datepicker.value = "2025-06-01";

<nys-datepicker
  label="Benefits enrollment deadline"
  value="2025-06-01"
></nys-datepicker>

// FormData submits the value as a string in YYYY-MM-DD format
// e.g. "2025-06-01"

Width

Set the width prop to adjust the width of the input field. Supported values:

• md: 200px (default)
• lg: 384px
• full: takes the full width of the parent container

<div style="display: flex; flex-direction: column; gap: 16px;">
  <nys-datepicker label="Medium width" width="md"></nys-datepicker>
  <nys-datepicker label="Large width" width="lg"></nys-datepicker>
  <nys-datepicker label="Full width" width="full"></nys-datepicker>
</div>

Custom Start Date

Set startDate to open the calendar to a specific month. This is helpful when the expected date is far from today, such as a fiscal year start or a future project deadline. The value must be in YYYY-MM-DD format.

<nys-datepicker
  label="Fiscal year start date"
  description="Select the first day of the fiscal year"
  startDate="2026-04-01"
></nys-datepicker>

Hiding Buttons

The calendar popup includes "Today" and "Clear" buttons by default. Hide them with hideTodayButton and hideClearButton when you need users to intentionally select a specific date.

<nys-datepicker
  label="Court appearance date"
  hideTodayButton
  hideClearButton
></nys-datepicker>

Required

Set required to make the date field mandatory. The component displays a "Required" flag next to the label and validates on blur.

<nys-datepicker
  label="Application submission date"
  description="Only dates within April 4/5/2026 - 4/15/2026 are selectable"
  minDate="2026-04-05"
  maxDate="2026-04-15"
></nys-datepicker>

Optional

Set optional to display an "Optional" flag. Use this when most fields in the form are required and you need to call out the few that are not.

<nys-datepicker
  label="Preferred callback date"
  optional
></nys-datepicker>

Tooltip

Set tooltip to display an info icon with hover text that provides additional context about the field.

<nys-datepicker
  label="Inspection date"
  tooltip="The date your vehicle was last inspected by an authorized station"
></nys-datepicker>

Error Message

Set errorMessage to define custom error text. The message only appears when showError is also set. When used with required, the component automatically validates on blur and shows errors after the first interaction.

<nys-datepicker
  label="Permit expiration date"
  showError
  errorMessage="A valid expiration date is required to continue"
></nys-datepicker>

Disabled

Set disabled to prevent interaction. The calendar button and input are both disabled, and the field is excluded from form submission.

<nys-datepicker
  label="Registration date"
  disabled
  value="2025-01-15"
></nys-datepicker>

Usage

When to use this component

• When users need to select a single calendar date, such as scheduling an appointment or choosing a filing deadline
• When the day of the week matters and a calendar view helps users orient themselves
• When a form requires consistent date formatting across browsers

When to consider something else

• For familiar dates where users already know the value without a calendar, such as date of birth or document issue dates. Consider memorable date fields (currently under proposal).
• When users need to select multiple dates or a span of time. Consider a date range component (possible version 2 of nys-datepicker).
• When time selection is required alongside the date.

Properties

Form Prop

The form property associates this component with a <form> element by ID, even if the component is not a descendant of that form. See Form Patterns for details on form association and ElementInternals.

Style Overrides

Events

The <nys-datepicker> component emits two custom JavaScript events:

1. nys-input -- Fired when the user selects or types a valid date.
2. nys-blur -- Fired when the input or calendar loses focus. Triggers validation.

Event details

The nys-input event includes a detail object with the following properties:

• id (string): The id of the datepicker component.
• value (Date): The selected date as a Date object.

The nys-blur event is a plain Event with no additional detail.

You can listen to these events using JavaScript:

// Select the datepicker component
const datepicker = document.querySelector("nys-datepicker");
// Listen for date selection
datepicker.addEventListener("nys-input", (event) => {
const { id, value } = event.detail;
console.log(</span><span class="token string">Datepicker (</span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>id<span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">) date selected:</span><span class="token template-punctuation string">, value);
});
// Listen for blur (triggers validation)
datepicker.addEventListener("nys-blur", () => {
console.log("Datepicker lost focus");
});