DatePicker

Single-date field with a calendar, keyboard navigation, and blocked dates.

Overview

  • Values contain a date without a time or time zone.

Aliases

calendar picker

When to use

  • Use DatePicker when users need help choosing a calendar date rather than typing one from memory.
  • Set min, max, and disabledDates to constrain selection.

When not to use

  • Do not use DatePicker for ranges, times, or multi-month planning.
  • Pass date-only values; convert timestamps in your app before passing them.

Structural parts

field wrapper

root

Provides the field label, helper text, and validation state.

field button

trigger

Opens the calendar surface and displays the chosen date.

date grid surface

calendar

Anchored calendar surface with month navigation.

grid cell button

day

Selectable calendar day with range and disabled rules.

Public interface

Props
NameTypeDefaultDescription
labelstring—Visible label used for the field or control.
descriptionstring—Provides field guidance associated with the control.
errorstring—Shows a validation error associated with the control.
placeholderstring—Placeholder text shown before a user makes a selection or enters text.
requiredbooleanfalseMarks the control as required.
disabledbooleanfalsePrevents interaction and exposes the disabled state.
namestring—Form field name used for native form submission.
idstring—Sets the control ID for external labels and descriptions.
size'sm' | 'md' | 'lg''md'Sets the component size.
valuestring—Controlled date-only value in YYYY-MM-DD format.
minstring—Minimum selectable date in YYYY-MM-DD format.
maxstring—Maximum selectable date in YYYY-MM-DD format.
disabledDatesstring[]—Explicitly blocked date-only values.
weekStartsOn0 | 10Chooses Sunday or Monday as the first day of the week.
onChange(detail: { value: string | undefined }) => void—Runs when a valid date is selected.
themeThemeContract—Sets the theme used to resolve component styles.
Events
NamePayloadDescription
change{ value: string | undefined }Fires when the component commits a new value.
Slots
NameDescription
defaultDatePicker is prop-driven and does not expose custom slots.

Variants, sizes, and states

Variants

  • default: DatePicker uses one single-date shell and varies by size.

Sizes

  • sm: Compact date field for dense tools.
  • md: Default date field size.
  • lg: Larger date field for touch-friendly surfaces.

States

  • closed: Date field is idle and the calendar is hidden.
  • open: Calendar surface is visible.
  • selected: A date has been committed to the field.
  • disabled: Date field cannot open or change.
  • blocked: Specific days cannot be selected due to range or explicit block rules.

Accessibility

Semantics

  • Associates the control with its visible label, description, and error.
  • Exposes disabled and required semantics through the underlying form control.
  • Uses a labeled trigger button paired with an anchored date grid surface.

Keyboard

  • Supports native focus and text entry behavior.
  • Arrow keys move day focus, Home and End move within a week, and PageUp/PageDown change month.
  • Enter or Space selects the focused valid day and Escape closes the surface.

Screen readers

  • Connects visible label, helper text, and error text to the native control.
  • The trigger exposes the current selected date and the calendar surface announces the active month and focused day.

Caveats

  • DatePicker uses date-only values (YYYY-MM-DD) and intentionally avoids timestamp semantics.

Checklist

  • Verify that the control has an accessible name.
  • Verify that keyboard focus is visible in every state and size.
  • Identify disabled, selected, and error states with text or symbols as well as color.

Tokens and CSS variables

root

--dk-field-stack-gap
0.45rem
--dk-date-picker-offset
8px
--dk-motion-duration
200ms

label

--dk-field-label-color
#16181c
--dk-field-label-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-field-label-weight
600

trigger

--dk-date-picker-trigger-bg
#f2f5fb
--dk-date-picker-trigger-fg
#16181c
--dk-date-picker-trigger-border
#95989d
--dk-date-picker-trigger-radius
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-date-picker-trigger-block-size
48px
--dk-date-picker-trigger-inline-padding
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-date-picker-trigger-font-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)

icon

--dk-date-picker-icon-size
1rem
--dk-date-picker-icon-color
#16181c

description

--dk-field-description-color
#16181c
--dk-field-description-size
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

error

--dk-field-error-color
#cc272e
--dk-field-error-size
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

surface

--dk-date-picker-surface-bg
#f2f5fb
--dk-date-picker-surface-fg
#16181c
--dk-date-picker-surface-border
#95989d
--dk-date-picker-surface-radius
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-date-picker-surface-shadow
0 10px 15px rgba(0, 0, 0, 0.06), 0 4px 6px rgba(0, 0, 0, 0.04)
--dk-date-picker-surface-width
320px
--dk-date-picker-surface-padding
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)

caption

--dk-date-picker-caption-color
#16181c
--dk-date-picker-caption-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-date-picker-caption-weight
700

navButton

--dk-date-picker-nav-bg
#e5e8ed
--dk-date-picker-nav-fg
#16181c
--dk-date-picker-nav-size
36px

weekday

--dk-date-picker-weekday-color
#16181c
--dk-date-picker-weekday-size
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

day

--dk-date-picker-day-bg
#f2f5fb
--dk-date-picker-day-fg
#16181c
--dk-date-picker-day-radius
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-date-picker-day-size
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-date-picker-day-target
44px
--dk-date-picker-day-today-ring
#2072e4
--dk-date-picker-day-disabled-fg
#16181c
--dk-date-picker-day-outside-fg
#95989d

Implementation notes

  • DatePicker supports one date. Use RangeDatePicker for a date range.

Examples

Starter

Choose one launch date

A standard single-date field with a selected value.

<DatePicker label="Launch date" value="2026-04-15" />

Common patterns

Min and max constraints

Limit the valid date window when the workflow has a real schedule boundary.

<DatePicker label="Ship date" min="2026-04-01" max="2026-04-30" />

Edge cases

Blocked dates

Block specific non-working days or unavailable release slots.

<DatePicker label="Launch date" disabledDates={['2026-04-19', '2026-04-20']} />

Mathematical fixtures

Calculated fixtures; browser evidence is not collected. Layout estimates use declared text behavior and maximum token values.

default-md

pass

size=md

  • Evidence: mathematical
  • Coverage: complete (4 / 4 declared kinds evaluated)
  • Declared: contrast, target, anchoredSurface, layout
  • Evaluated: contrast, target, anchoredSurface, layout
  • Contrast: 98.5 Lc, 98.5 Lc
  • Target: 48 px, 44 px
  • Layout: surface · single-line 0 px single-line estimate; 0 px minimum width
    280 px: pass 320 px: pass 360 px: pass
  • Surface: 320 × 324 px

selected-lg

pass

size=lg

  • Evidence: mathematical
  • Coverage: complete (4 / 4 declared kinds evaluated)
  • Declared: contrast, target, anchoredSurface, layout
  • Evaluated: contrast, target, anchoredSurface, layout
  • Contrast: 98.5 Lc, 76.6 Lc
  • Target: 52 px, 44 px
  • Layout: surface · single-line 0 px single-line estimate; 0 px minimum width
    280 px: pass 320 px: pass 360 px: pass
  • Surface: 320 × 324 px

disabled-sm

pass

size=sm

  • Evidence: mathematical
  • Coverage: complete (4 / 4 declared kinds evaluated)
  • Declared: contrast, target, anchoredSurface, layout
  • Evaluated: contrast, target, anchoredSurface, layout
  • Contrast: 98.5 Lc, 98.5 Lc
  • Target: 44 px, 44 px
  • Layout: surface · single-line 0 px single-line estimate; 0 px minimum width
    280 px: pass 320 px: pass 360 px: pass
  • Surface: 320 × 324 px