Skip to main content
On this pageOverview

Date Picker

Overview

An accessible date picker that wraps Calendar in a Popover. Consumers provide the trigger button face and the calendar grid layout. DatePicker handles focus choreography (opening focuses the grid, closing returns focus to the trigger), open/close state, and an optional hidden form input for native form submission.

State Ownership

DatePickerBlock is a completed Block. Declare its startup arguments on the Binding, register that Binding in the parent Composition, and render it through Binding.embedView. The Composition update routes the generated child envelope through the Binding automatically.

The parent owns the selected date. Store it in the parent Model, pass it to the view as maybeSelectedDate, and handle SelectedDate and ClearedDate in the Binding's selected fold policy. DatePicker can also emit ChangedViewMonth when navigation changes the visible month.

Programmatic Control

For programmatic control in a parent update, call the Binding’s requestOpen() and requestClose() operations. They update the child through DatePicker update and do not emit an OutMessage.

Calendar Views

The calendar heading inside the popover is a button: clicking it switches the day grid into a 3x4 months grid; clicking the year heading from there switches into a paged 3x4 years grid. Selecting a year drills back to the months grid for that year; selecting a month drills back to the days grid for that month. Re-opening the popover always shows the day grid.

See it in an app

Check out how DatePicker is wired up in a real Foldkit app.

Examples

A date picker constrained to a one-year window around today via minDate and maxDate. Click the trigger to open, pick a date, click the heading to drill into a months grid (and again to drill into a years grid), or navigate with the full WAI-ARIA grid keyboard pattern. Press Enter to commit, Escape to dismiss.

Date picker

Styling

DatePicker is headless. You control the trigger button via triggerContent and triggerClassName, the popover panel via panelClassName, and the calendar grid via the toCalendarView callback. Data attributes on day cells let you style state variants with CSS selectors like group-data-[selected]: and group-data-[disabled]:.

AttributeCondition
data-todayPresent on the cell representing "today". The day cell in Days mode, the current month cell in Months mode, the current year cell in Years mode.
data-selectedPresent on the calendar's currently-centered cell. The selected date in Days mode, the centered month (viewMonth) in Months mode, the centered year (viewYear) in Years mode.
data-focusedPresent on the cell at the keyboard cursor position while the grid has DOM focus.
data-outside-month(Days mode only.) Present on cells that fall outside the currently-viewed month (leading/trailing grid rows).
data-disabledPresent on cells disabled by min/max, disabledDaysOfWeek, or disabledDates.
data-openPresent on the trigger button and wrapper while the popover is open.
data-placementPresent on the calendar panel, set to the side it currently sits on: top, right, bottom, or left. Fixed to the first resolved side when isPlacementLocked is true.

Keyboard Interaction

The trigger button opens the popover on Enter, Space, or ArrowDown. Inside the popover, the calendar grid handles the full WAI-ARIA grid keyboard pattern. Escape closes the popover from both the trigger and the grid.

KeyDescription
Enter / Space / ArrowDownOpen the popover when the trigger button is focused.
EscapeClose the popover from the trigger button or from inside the calendar grid.
ArrowLeft / ArrowRightMove the focus cursor by one cell. Days: ±1 day. Months: ±1 month (wraps across years). Years: ±1 year (wraps across pages).
ArrowUp / ArrowDownMove the focus cursor by one row. Days: ±1 week (7 days). Months: ±1 row (3 months). Years: ±1 row (3 years).
Home / End(Days mode only.) Move focus to the start / end of the current week (based on locale.firstDayOfWeek).
PageUp / PageDownDays: ±1 month. Months: ±1 year. Years: ±1 window (12 years).
Shift + PageUp / Shift + PageDown(Days mode only.) Move focus by one year.
Enter / SpaceCommit the focus cursor. Days: select the date and close the popover. Months: jump the calendar to that month and drill back to Days. Years: jump to that year and drill back to Months.

Accessibility

The trigger button uses aria-expanded and aria-controls to announce the popover relationship. Inside the popover, the calendar grid renders with role="grid" and an explicit aria-label that leads with a non-numeric word ("Calendar, April 2026") so VoiceOver does not pattern-match the grid's row position into a date literal. aria-activedescendant tracks the keyboard cursor; rows carry role="row" with aria-rowindex; cells carry role="gridcell", aria-colindex, and aria-selected on the chosen date. Day buttons carry full accessible names via aria-label and disabled days get aria-disabled="true". When a hidden form input is enabled via the name prop, the selected date is encoded as an ISO string (YYYY-MM-DD) for native form submission.

Naming the Trigger

Give the trigger an accessible name. For a visible label, wire a native <label for> that targets the trigger id with triggerId(id) imported from @foldkit/ui/datePicker rather than hardcoding the -popover-button convention. The for association makes the trigger properly labeled: assistive technology announces it by the visible label text, and clicking the label opens the date picker. That is why it is the recommended pattern.

Two ViewInputs fields cover the cases a <label for> does not. Pass ariaLabel for an icon-only trigger with no visible label, or ariaLabelledBy when the element that names the trigger is not a <label> you can point for at.

API Reference

InitConfig

Configuration passed to the DatePicker Binding's child initializer. Direct completed Block calls use DatePicker.DatePickerBlock.init(). Calendar constraints (min/max, disabled dates) are forwarded to the embedded Calendar Block.

NameTypeDefaultDescription
idstring—Unique ID for the date picker instance.
todayCalendarDate—The current calendar date. Typically fetched at the app boundary via Calendar.today.local and threaded through flags.
initialViewDateCalendarDate—Seeds the month the calendar opens onto. When set, the view starts on the month containing this date. The parent owns the selection itself; pass its current value here to open onto that month.
isAnimatedbooleanfalseEnables animation coordination on the popover panel (enter/leave animations).
localeLocaleConfigdefaultEnglishLocaleMonth and day names, the first day of the week, and the DateFormat for each shape the calendar renders. Import from foldkit/calendar.
minDateCalendarDate—Earliest selectable date. Dates before minDate are marked disabled and skipped by keyboard navigation.
maxDateCalendarDate—Latest selectable date. Dates after maxDate are marked disabled and skipped by keyboard navigation.
disabledDaysOfWeekReadonlyArray<DayOfWeek>[]Days of the week to disable (e.g. ["Saturday", "Sunday"] for weekday-only selection).
disabledDatesReadonlyArray<CalendarDate>[]Explicit list of disabled dates (e.g. holidays). Pre-compute for complex rules.

Model

The DatePicker Model. Store DatePicker.DatePickerBlock.Model on the parent Model; the registered Binding routes update and embeds the completed Block's view.

NameTypeDefaultDescription
idstring—The date picker instance ID.
calendarCalendarBlock.Model—The embedded Calendar block. Forwards navigation, focus, locale, and disabled-cell state. The picker delegates Calendar messages and resets the calendar to Days mode every time the popover opens or closes.
popoverPopoverBlock.Model—The embedded Popover block. Tracks open/close state, animation phase, and focus choreography (opening focuses the calendar grid, closing returns focus to the trigger).

ViewInputs

Pass the child Model as model and these fields as viewInputs to the DatePicker Binding's embedView method. The Binding supplies the canonical view, Message wrapper, and composition scope. Keep triggerContent and toCalendarView at the top level, and use childAttributes for handler-bearing attribute inputs; see Callback dispatch boundaries.

NameTypeDefaultDescription
maybeSelectedDateOption<CalendarDate>—The parent-owned selected date. Passed through to the calendar (selected-day marker), the trigger content, and the hidden form input. The picker does not store the selection itself; fold the SelectedDate and ClearedDate OutMessages into this field and pass it back on every render.
anchorAnchorConfig—Popover positioning config (placement, gap, offset, padding, isPlacementLocked, and portal). Controls where the calendar panel floats relative to the trigger. Portaled to the document body, or into an enclosing dialog, by default; pass portal: false to keep the panel inside its wrapper.
triggerContent(maybeDate: Option<CalendarDate>) => Html—Renders the trigger button face. Receives the current selection so you can show the formatted date or a placeholder.
toCalendarView(attributes: CalendarAttributes) => Html—Renders the calendar grid layout inside the popover panel. Same callback shape as Calendar.view toView. Lay out the attribute groups (for example grid, header, weeks, or cells) however you like.
isDisabledbooleanfalseDisables the trigger button, preventing the popover from opening.
namestring—When provided, renders a hidden <input> with this name and the selected date encoded as an ISO string (YYYY-MM-DD) for native form submission.
className / attributesstring / ReadonlyArray<ChildAttribute>—Class name and additional attributes spread onto the outer DatePicker wrapper.
triggerClassName / triggerAttributesstring / ReadonlyArray<ChildAttribute>—Class name and additional attributes spread onto the trigger button.
ariaLabelstring—Accessible name for the trigger button. Use for an icon-only trigger with no visible label. Applied as aria-label, and takes precedence over ariaLabelledBy.
ariaLabelledBystring—Id of an external element that labels the trigger button, applied as aria-labelledby. Pair with a visible label element.
previousMonthLabel / nextMonthLabelstring / stringEnglishAccessible labels for the Calendar's previous- and next-month buttons.
previousYearsPageLabel / nextYearsPageLabelstring / stringEnglishAccessible labels for the Calendar's previous- and next-page buttons in Years mode.
daysHeadingButtonLabel / monthsHeadingButtonLabelstring / stringEnglishAccessible labels for switching from Days to Months and from Months to Years.
toDaysGridLabel(monthYear: string) => stringEnglishBuilds the Days grid label from the locale-formatted heading.
toWeekLabel(weekStart: CalendarDate) => stringEnglishBuilds each week-row label from its first date.
toMonthsGridLabel(year: number) => stringEnglishBuilds the Months grid label from its displayed year.
toYearsGridLabel(startYear: number, endYear: number) => stringEnglishBuilds the Years grid label from the bounds of its displayed window.
panelClassName / panelAttributesstring / ReadonlyArray<ChildAttribute>—Class name and additional attributes spread onto the popover panel.
backdropClassName / backdropAttributesstring / ReadonlyArray<ChildAttribute>—Class name and additional attributes spread onto the click-outside backdrop.

CalendarAttributes

The discriminated union passed to toCalendarView. Pattern-match on _tag ('Days' | 'Months' | 'Years') with Match.tagsExhaustive to render each grid. Each variant exposes a different shape: Days carries weeks plus a headingButton; Months carries 12 month cells plus a headingButton; Years carries 12 year cells plus prev/next page buttons. See the Calendar page's CalendarAttributes section for the full prop table. The type is the same.

OutMessage

Messages emitted to the parent through the optional outMessage field. Handle the OutMessage in the Binding’s selected fold policy.

NameTypeDefaultDescription
SelectedDate{ date: CalendarDate }—Emitted when the user commits a date (click / Enter / Space). Handle it in the Binding's selected fold policy to lift the date into domain state.
ClearedDate{}—Emitted when the user clears the selected date (via Cleared or the Binding’s requestClear()). The popover stays open. Fold it into the parent-owned selected-date field by setting it to Option.none().
ChangedViewMonth{ year: number; month: number }—Emitted when navigation changes the visible month inside the calendar grid.

Programmatic Helpers

These child entry points let a parent request a controlled selection, focus change, open, or close, and inform the DatePicker when constraints derived from other Model state change. Each Binding call returns a connected parent Step, so return it from the parent handler or compose it with Update.combineSteps. Every child Model change then runs through DatePicker update.

The four inform*Changed operations implement cross-field date validation. Constraints are set at init time and updated through InformedOf*Change Messages. They do not live in ViewInputs, because update needs them for keyboard-navigation disabled-skipping and commit-time validation. For an end date that must be on or after a start date, call EndDatePickerBinding.informMinDateChanged(maybeStartDate) in the parent handler that processes the start date change. The notification branch returns { model } and does not echo an OutMessage.

Binding callArgumentsDescription
DatePickerBinding.requestSelectDate(date)date: CalendarDateRequests the given date. A disabled date leaves the child unchanged and emits nothing; otherwise DatePicker commits it, closes the popover, and emits SelectedDate. Use requestFocusDate to move onto a date without selecting it.
DatePickerBinding.requestFocusDate(date)date: CalendarDateDispatches RequestedFocusDate to move the embedded Calendar view and cursor without changing the selection. Use it after the parent sets its value from an external source so opening the picker shows that month. The branch itself emits no OutMessage.
DatePickerBinding.requestClear()NoneClears the selected date, emitting ClearedDate so the parent resets its own field. Does not close the popover.
DatePickerBinding.requestOpen()NoneProgrammatically opens the popover. Use it when the DatePicker should open in response to a parent event rather than a trigger click. It emits no DatePicker OutMessage.
DatePickerBinding.requestClose()NoneProgrammatically closes the popover. It emits no DatePicker OutMessage.
DatePickerBinding.informMinDateChanged(maybeMinDate)maybeMinDate: Option<CalendarDate>Dispatches InformedOfMinDateChange. Pass Option.none() to remove the minimum. Use it when an end date picker's minimum tracks a start date. It does not reconcile a current selection below the new minimum.
DatePickerBinding.informMaxDateChanged(maybeMaxDate)maybeMaxDate: Option<CalendarDate>Dispatches InformedOfMaxDateChange. Pass Option.none() to remove the maximum. It does not reconcile the current selection.
DatePickerBinding.informDisabledDatesChanged(disabledDates)disabledDates: ReadonlyArray<CalendarDate>Dispatches InformedOfDisabledDatesChange. Pass an empty array to clear the individually disabled dates.
DatePickerBinding.informDisabledDaysOfWeekChanged(disabledDaysOfWeek)disabledDaysOfWeek: ReadonlyArray<DayOfWeek>Dispatches InformedOfDisabledDaysOfWeekChange. Pass an empty array to clear the disabled weekdays.