On this pageOverview
Date Picker
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.
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.
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.
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.
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.
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]:.
| Attribute | Condition |
|---|---|
data-today | Present 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-selected | Present 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-focused | Present 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-disabled | Present on cells disabled by min/max, disabledDaysOfWeek, or disabledDates. |
data-open | Present on the trigger button and wrapper while the popover is open. |
data-placement | Present 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. |
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.
| Key | Description |
|---|---|
Enter / Space / ArrowDown | Open the popover when the trigger button is focused. |
Escape | Close the popover from the trigger button or from inside the calendar grid. |
ArrowLeft / ArrowRight | Move the focus cursor by one cell. Days: ±1 day. Months: ±1 month (wraps across years). Years: ±1 year (wraps across pages). |
ArrowUp / ArrowDown | Move 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 / PageDown | Days: ±1 month. Months: ±1 year. Years: ±1 window (12 years). |
Shift + PageUp / Shift + PageDown | (Days mode only.) Move focus by one year. |
Enter / Space | Commit 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. |
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.
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.
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.
| Name | Type | Default | Description |
|---|---|---|---|
id | string | — | Unique ID for the date picker instance. |
today | CalendarDate | — | The current calendar date. Typically fetched at the app boundary via Calendar.today.local and threaded through flags. |
initialViewDate | CalendarDate | — | 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. |
isAnimated | boolean | false | Enables animation coordination on the popover panel (enter/leave animations). |
locale | LocaleConfig | defaultEnglishLocale | Month and day names, the first day of the week, and the DateFormat for each shape the calendar renders. Import from foldkit/calendar. |
minDate | CalendarDate | — | Earliest selectable date. Dates before minDate are marked disabled and skipped by keyboard navigation. |
maxDate | CalendarDate | — | Latest selectable date. Dates after maxDate are marked disabled and skipped by keyboard navigation. |
disabledDaysOfWeek | ReadonlyArray<DayOfWeek> | [] | Days of the week to disable (e.g. ["Saturday", "Sunday"] for weekday-only selection). |
disabledDates | ReadonlyArray<CalendarDate> | [] | Explicit list of disabled dates (e.g. holidays). Pre-compute for complex rules. |
The DatePicker Model. Store DatePicker.DatePickerBlock.Model on the parent Model; the registered Binding routes update and embeds the completed Block's view.
| Name | Type | Default | Description |
|---|---|---|---|
id | string | — | The date picker instance ID. |
calendar | CalendarBlock.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. |
popover | PopoverBlock.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). |
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.
| Name | Type | Default | Description |
|---|---|---|---|
maybeSelectedDate | Option<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. |
anchor | AnchorConfig | — | 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. |
isDisabled | boolean | false | Disables the trigger button, preventing the popover from opening. |
name | string | — | 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 / attributes | string / ReadonlyArray<ChildAttribute> | — | Class name and additional attributes spread onto the outer DatePicker wrapper. |
triggerClassName / triggerAttributes | string / ReadonlyArray<ChildAttribute> | — | Class name and additional attributes spread onto the trigger button. |
ariaLabel | string | — | 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. |
ariaLabelledBy | string | — | Id of an external element that labels the trigger button, applied as aria-labelledby. Pair with a visible label element. |
previousMonthLabel / nextMonthLabel | string / string | English | Accessible labels for the Calendar's previous- and next-month buttons. |
previousYearsPageLabel / nextYearsPageLabel | string / string | English | Accessible labels for the Calendar's previous- and next-page buttons in Years mode. |
daysHeadingButtonLabel / monthsHeadingButtonLabel | string / string | English | Accessible labels for switching from Days to Months and from Months to Years. |
toDaysGridLabel | (monthYear: string) => string | English | Builds the Days grid label from the locale-formatted heading. |
toWeekLabel | (weekStart: CalendarDate) => string | English | Builds each week-row label from its first date. |
toMonthsGridLabel | (year: number) => string | English | Builds the Months grid label from its displayed year. |
toYearsGridLabel | (startYear: number, endYear: number) => string | English | Builds the Years grid label from the bounds of its displayed window. |
panelClassName / panelAttributes | string / ReadonlyArray<ChildAttribute> | — | Class name and additional attributes spread onto the popover panel. |
backdropClassName / backdropAttributes | string / ReadonlyArray<ChildAttribute> | — | Class name and additional attributes spread onto the click-outside backdrop. |
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.
Messages emitted to the parent through the optional outMessage field. Handle the OutMessage in the Binding’s selected fold policy.
| Name | Type | Default | Description |
|---|---|---|---|
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. |
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 call | Arguments | Description |
|---|---|---|
DatePickerBinding.requestSelectDate(date) | date: CalendarDate | Requests 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: CalendarDate | Dispatches 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() | None | Clears the selected date, emitting ClearedDate so the parent resets its own field. Does not close the popover. |
DatePickerBinding.requestOpen() | None | Programmatically 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() | None | Programmatically 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. |