Datepicker

The <nys-datepicker> component allows users to select a date from a visual calendar or type a date into the input field.

Options

Value and form output

The value prop can be set as a Date object or an ISO date string (YYYY-MM-DD). Outwards, the input displays it as (mm/dd/yyyy). Internally, the component stores and submits the value as a string in ISO format.

Valid value examples

// Using a Date object
value = new Date(2025, 5, 1) // June 1, 2025
// Using a string
value = "2025-06-01"

<nys-datepicker value="2025-06-01"></nys-datepicker>

// FormData submits a string in YYYY-MM-DD format
2025-06-01

Width

Set the width prop to adjust the width of <nys-datepicker> Supported widths are:

• md: 200px (default width)
• lg: 384px
• full: will take up 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

Use this option to guide users toward a relevant time period without preselecting a date.

<nys-datepicker label="Project start date" startDate="2024-01-01"></nys-datepicker>

Hiding Buttons

Hide the Today and Clear buttons to require users to intentionally choose a date.
Use properties hideTodayButton and hideClearButton to toggle off the buttons

<nys-datepicker
  label="Select a date"
  hideTodayButton
  hideClearButton
></nys-datepicker>

Disabled

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

Usage

When to use this component

• When users need to select a single calendar date
• When a form requires consistent date formatting across browsers
• When native date picker behavior needs to be replaced with a controlled, accessible experience

When to consider something else

• Familiar dates where users know the value without a calendar, such as a date of birth. Consider memorable date fields (currently under proposal)
• When the day of the week is irrelevant, such as birthdays 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

Accessibility

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

• Uses native <input type="date"> semantics for screen reader support
• Supports keyboard interaction to open and navigate the calendar
• Applies aria-required, aria-disabled, and validation messaging
• Error messages are announced via associated error messaging

Properties

CSS Variables

Events

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

1. nys-input – Emitted when the datepicker input text changes.
2. nys-blur – Emitted when the datepicker input loses focus.

Event details

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

• id (string): The id of the datepicker.
• value (Date): The current value of the datepicker. Updates when a new valid date is set.

You can listen to these events using JavaScript:

// Select the datepicker component
const datepicker = document.querySelector("nys-datepicker");
// Listen for the 'nys-input' event
datepicker.addEventListener('nys-input', (event) => {
  const { id, value } = event.detail;
  console.log(`Datepicker (${id}) value has changed: `, value);
});