Forms

DatePicker

A fully accessible date picker with year→month→day drill-down, calendar popup, input masking, and healthcare-specific features like age calculation. Click the month or year in the header to jump to year or month selection. Essential for patient registration, appointment scheduling, and coverage management.

Year → Month → Day drill-down

Open the calendar and click the month name or year in the header to zoom out to month or year view. Select a year to see months, then a month to see days. Perfect for dates of birth or any date far from today.

Pick any date

DatePicker in a Modal

Click the button to open a small modal containing a DatePicker. The modal uses scrollBehavior outside so the calendar popup is not clipped. The DatePicker has a hint; the footer reserves space so selecting a date (and showing age or replacing the hint) does not cause layout shift.

Date of Birth with Age

For patient registration forms. Shows calculated age and prevents future dates.

Date of Birth

Appointment Scheduling

For scheduling future appointments. Prevents past dates and weekends.

Appointment Date

Coverage Period

For insurance coverage dates with min/max constraints.

Coverage Start Date

Coverage End Date

Date Formats

Support for different date formats based on locale or requirements.

US Format (MM/DD/YYYY)

European Format (DD/MM/YYYY)

ISO Format (YYYY-MM-DD)

Service Date

For healthcare claims and billing. Allows any date within reasonable range.

Date of Service

Sizes

Choose appropriate sizes based on form density.

Small Date

Medium Date

Large Date

Validation States

Shows error and success states for form validation.

With Error

With Success

Disabled & Read-only

Use disabled for unavailable fields and read-only for view-only data.

Admission Date

Discharge Date

Props

Prop	Type	Default	Description
`label` *	`string`	—	Input label text
`value`	`string`	''	ISO date string (YYYY-MM-DD) - bindable
`format`	`'MM/DD/YYYY' \| 'DD/MM/YYYY' \| 'YYYY-MM-DD'`	'MM/DD/YYYY'	Display format for the date
`placeholder`	`string`	—	Placeholder text (defaults to format)
`required`	`boolean`	false	Marks field as required
`disabled`	`boolean`	false	Disables the input
`readonly`	`boolean`	false	Makes input read-only
`error`	`string`	—	Error message to display
`hint`	`string`	—	Helper text shown on focus
`successMessage`	`string`	—	Success message when valid
`size`	`'sm' \| 'md' \| 'lg'`	'md'	Input size
`showAge`	`boolean`	false	Show age calculation (for DOB)
`minDate`	`Date`	—	Minimum selectable date
`maxDate`	`Date`	—	Maximum selectable date
`disablePast`	`boolean`	false	Disable dates in the past
`disableFuture`	`boolean`	false	Disable dates in the future
`isDateDisabled`	`(date: Date) => boolean`	—	Custom function to disable specific dates
`clearable`	`boolean`	false	Show clear button
`validateOnMount`	`boolean`	false	Show validation state immediately
`onchange`	`(value: string, date: Date \| null) => void`	—	Called when value changes
`onopen`	`() => void`	—	Called when calendar opens
`onclose`	`() => void`	—	Called when calendar closes
`onclear`	`() => void`	—	Called when clear button is clicked
`alwaysShowFooter`	`boolean`	false	When true, the message footer (hint/error/success/age) is always rendered with reserved space to prevent layout shift when content appears (e.g. age on select, hint on focus). Use when hint or validation is set dynamically.

Drill-down & keyboard

Click: In the calendar header, click the month name to open the month grid, or the year to open the year grid. Select a year → then a month → then a day. Escape goes back (year → month → day → close).

Key	Action
`Alt + ↓`	Open calendar
`Escape`	Back (year→month→day) or close calendar
`← → ↑ ↓`	Navigate days, months, or years (depending on view)
`Home` / `End`	First/last day of month (day view)
`Page Up/Down`	Prev/next month (day view) or prev/next year (month view) or prev/next year range (year view)
`Shift + Page Up/Down`	Prev/next year (day view)
`Enter` / `Space`	Select focused day, month, or year

Message footer & layout shift

The message footer (hint, error, success, age) is shown in a reserved area below the input. To avoid layout shift when content appears or changes (e.g. hint on focus, age when a date is selected), the footer is rendered whenever the component can show any of that content—even if nothing is visible yet. When there is nothing to display, an invisible placeholder reserves one line of space.

Default: Footer is shown when the component has a hint, error, successMessage, or showAge. Footer is hidden only when none of these are set.
alwaysShowFooter: Set to true to always reserve footer space (e.g. when your app sets hint or error dynamically).

Healthcare Best Practices

• Use showAge for Date of Birth fields - critical for patient identification and dosing
• Use disableFuture for DOB and service dates to prevent data entry errors
• Use disablePast for appointment scheduling to only allow future dates
• Use minDate/maxDate for coverage periods to enforce valid date ranges
• Use isDateDisabled to block weekends, holidays, or unavailable dates
• Always provide clear labels that describe the clinical purpose
• Use clearable for optional date fields to allow easy reset

Accessibility Features

• WAI-ARIA Dialog Pattern: Calendar popup follows W3C APG date picker dialog pattern
• Year → Month → Day drill-down: Click month or year in header to jump; Escape steps back
• Full Keyboard Navigation: Arrow keys in day, month, and year views; Home/End, PageUp/PageDown, Enter/Space/Escape
• Focus Trap: Tab key cycles within calendar when open
• Focus Restoration: Focus returns to trigger button when calendar closes; focus moves to first item when switching views
• Live Announcements: Month/year changes and view changes announced to screen readers
• ARIA Grid: Day calendar and month/year grids use appropriate roles and labels
• Accessible Labels: Each day/month/year control has a clear label for screen readers
• Reduced Motion: Respects prefers-reduced-motion for view transitions

Value Format

The value prop always uses ISO 8601 format (YYYY-MM-DD) regardless of the display format. This ensures consistent data storage and makes it easy to work with Date objects and APIs. The format prop only affects how the date is displayed to users.