Date Picker

Material Design 3 date picker for selecting a single date with a calendar overlay. Not intended for date-range planning with complex constraints or timeline editing workflows.

Basic Usage

Use a date picker to select a single date. The calendar overlay reduces input errors compared to manual date typing. 

<ds-date-picker label="Select a date"></ds-date-picker>

Initial Value

Provide a pre-selected value in ISO format.

<ds-date-picker label="Event date" value="2024-12-25"></ds-date-picker>

Variants

Use constraints and localization for different contexts.

Date Constraints

<ds-date-picker label="Future dates" min="2025-01-01"></ds-date-picker>
<ds-date-picker label="Past dates" max="2024-12-31"></ds-date-picker>
<ds-date-picker
  label="Within range"
  min="2024-12-01"
  max="2024-12-31"
  value="2024-12-15"></ds-date-picker>

Localization

Set the locale for the formatted date display.

<ds-date-picker locale="en-US"></ds-date-picker>
<ds-date-picker locale="en-GB"></ds-date-picker>
<ds-date-picker locale="de-DE"></ds-date-picker>

States

Use disabled or required where appropriate.

<ds-date-picker label="Disabled" value="2024-12-25" disabled></ds-date-picker>
<ds-date-picker label="Required" required></ds-date-picker>

Interactive Example

Listen to change events for the selected date.

Select a date to see details...

API

Attributes

Attribute Type Default Description
name string "" Form field name. The ISO date is submitted under it; without a name the field is left out.
value string "" Selected date in YYYY-MM-DD format
min string "" Minimum selectable date
max string "" Maximum selectable date
label string "Select date" Input label text
disabled boolean false Disables the picker
required boolean false Marks the field as required
locale string "en-US" Locale for formatting

Forms

Submits the date as YYYY-MM-DD, "" when empty, like a native date input. Dates are read and written in local time, so the submitted day is the day the user clicked in every timezone. It resets with its form, and a disabled <fieldset> disables it. form, validity, validationMessage, checkValidity() and reportValidity() behave as on a native control.

Properties

Property Type Description
value string Get/set the selected date string
min string Get/set the minimum selectable date
max string Get/set the maximum selectable date
label string Get/set the input label
disabled boolean Get/set disabled state
required boolean Get/set required state
locale string Get/set locale for formatting

Events

Event Detail Description
ds-date-picker:change { value, date } Fired when a date is selected
ds-date-picker:open — Fired when the calendar opens
ds-date-picker:close — Fired when the calendar closes

Methods

Method Parameters Description
openCalendar() none Opens the calendar dropdown
closeCalendar() none Closes the calendar dropdown
selectDate(date) date: Date Selects a date programmatically
previousMonth() none Navigate to the previous month
nextMonth() none Navigate to the next month

CSS Parts

Part Description
input Input field element
calendar Calendar dropdown container
day Calendar day buttons

CSS Custom Properties

Property Description
--ds-date-picker-width Width of the input field
--ds-date-picker-input-padding-y Input vertical padding
--ds-date-picker-input-padding-x Input horizontal padding
--ds-date-picker-input-icon-padding Right padding for calendar icon
--ds-date-picker-label-offset-x Label left offset
--ds-date-picker-label-padding-x Label horizontal padding
--ds-date-picker-label-bg Label background color
--ds-date-picker-icon-offset-x Icon right offset
--ds-date-picker-icon-size Calendar icon size
--ds-date-picker-calendar-width Minimum calendar width
--ds-date-picker-calendar-padding Calendar padding
--ds-date-picker-calendar-gap Calendar grid gap
--ds-date-picker-header-gap Header spacing
--ds-date-picker-nav-size Navigation button size
--ds-date-picker-day-header-padding Day header padding
--ds-date-picker-day-font-size Day number font size

Accessibility

  • ✅ Escape key closes the calendar
  • ✅ Date buttons include full aria-labels
  • ✅ Calendar uses dialog role
  • ✅ Disabled state prevents interaction

Usage Guidelines

When to Use

  • When users need to select a specific date
  • For scheduling and booking interfaces
  • When date context is important

Best Practices

  • Always provide a clear label
  • Use min/max to prevent invalid dates
  • Match locale to the user context