DatePicker
Calendar popup to select a single date, multiple dates or a range. Supports month and year navigation with animated view transitions.
Preview
Rendering the live preview…
defaultRendering the live preview…
rangeRendering the live preview…
no headerRendering the live preview…
landscapeStructure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-date-picker> — 5 regions: root ①, header strip ②, navigation controls ③, day grid ④, and optional actions ⑤.- 1.origam-date-picker
- Root element. Fixed width 328px (368px with showWeek). Built on OrigamPicker with overflow:hidden. Modifier --year / --months applied while switching view.
- 2OrigamDatePickerHeader
- Coloured header strip (background from header.background-color token = color.action.primary.bg). Shows the selected date. Hidden via hideHeader prop. Replaced by the #header slot.
- 3OrigamDatePickerControls
- Navigation bar with prev/next arrow buttons and a text button that toggles between month, months and year views.
- 4OrigamDatePickerMonth
- Day-grid view. Weekday labels row + 6 rows of day buttons. Day cells use day.size (40px) and day.border-radius (full). Animated via OrigamFade when switching views.
- 5#actions slot
- Optional action buttons row. Use for Cancel / OK confirmation pattern. Only rendered when the #actions slot is provided.
API
Props
All props accepted by this component, with their type, default value and description.
- modelValuestring | Date | Array<string | Date>
- Selected date(s). Single value for single mode; array for multiple or range mode.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- color
- Intent or custom colour used for the selected day/month/year and the header background.
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>false
- Applies a border around the picker surface.
- borderTopboolean | number | string
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- Border-radius of the picker surface.
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- elevationTElevation
- Box-shadow elevation of the picker surface.
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- landscapebooleanfalse
- Displays the header on the left side and the calendar on the right (landscape orientation).
- hideHeaderbooleanfalse
- Hides the coloured header strip showing the selected date.
- sideTDirectionBoth
- swipeableboolean
- snapPointsReadonlyArray<TSheetSnapPoint>
- defaultSnapTSheetSnapId
- openboolean
- disabledboolean
- persistentboolean
- handleLabelstring
- tagstring
- bgColorTColor
- heightnumber | string
- maxHeightnumber | string
- maxWidthnumber | string
- minHeightnumber | string
- minWidthnumber | string
- widthnumber | string
- locationTAnchor
- positionTPosition
- topnumber | string
- bottomnumber | string
- leftnumber | string
- rightnumber | string
- activeboolean | IStateEffectConfig
- activeClassstring
- hoverboolean | IStateEffectConfig
- hoverClassstring
- titlestring
- Override text shown in the picker header.
- fontSizeTFontSize
- fontWeightTFontWeight
- letterSpacingTLetterSpacing
- textstring
- disabledMonthboolean
- disabledYearboolean
- disabledNextboolean
- disabledPrevboolean
- nextIconTIcon
- prevIconTIcon
- modeIconTIcon
- Current calendar view. 'month' shows day grid; 'months' shows month grid; 'year' shows year list.
- hideWeekdaysbooleanfalse
- Hides the weekday labels (Mon, Tue…) above the day grid.
- multipleboolean | number | TAnyStringfalse
- Enables multi-date selection. Pass a number to limit how many dates can be selected.
- rangebooleanfalse
- Enables date-range selection mode (start date + end date). modelValue should be an array of two dates.
- showWeekbooleanfalse
- Shows week numbers in the first column of the day grid.
- transitionTTransitionProps
- reverseTransitionTTransitionProps
- allowedDatesArray<unknown> | ((date: unknown) => boolean)
- displayValueunknown
- dateReadonlyArray<unknown> | Array<unknown>
- monthnumber
- maxunknown
- Maximum selectable date. Dates after this value are disabled.
- minunknown
- Minimum selectable date. Dates before this value are disabled.
- showAdjacentMonthsboolean
- yearnumber
- weekdaysArray<number>
- weeksInMonthTCalendarStrategy
- firstDayOfWeeknumber
- headerstring
- appendAvatarstring
- appendIconTIcon
- prependAvatarstring
- prependIconTIcon
- prependAriaLabelstring
- appendAriaLabelstring
- densityTDensity
API
Slots
Content slots exposed by this component.
- #title
- Custom title rendered inside the picker header strip.
- #header
- Full override of the header area. Replaces OrigamDatePickerHeader. Receives header text and click handler as slot props.
- #default
- Full override of the calendar body (controls + day/month/year grid). Use for deeply customised pickers.
- #actions
- Action buttons rendered below the calendar. Common use: "Cancel" and "OK" buttons to confirm the selection.
API
Emits
Events emitted by this component.
- @update:monthnumber
- Fired when the displayed month changes via navigation.
- @update:yearnumber
- Fired when the displayed year changes via navigation.
- @update:viewModeTDateMode
- Fired when the view changes (month → months → year → month).
- @update:modelValueany
- Fired when the selected date(s) change.
API
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- <T extends object>(props: T, exclude?: string[]) => Partial<T>
- Utility to forward a filtered subset of props.
- Ref<string>
- Reactive CSS string for the injected style sheet.
- string
- Unique style-sheet ID for this instance.
- () => void
- Injects the style sheet into the document.
- () => void
- Removes the style sheet from the document.
- Ref<boolean>
- True once the style sheet has been injected.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- Picker surface background colour.
- Picker surface foreground colour.
- Picker surface border-radius.
- Header strip background (selected-date display area).
- Header strip text colour.
- Size (width and height) of day buttons in the day grid.
- Border-radius of day buttons (full circle by default).
- Background of the selected day button.
- Background of days within a selected date range.
- Text colour of days outside the current month.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
Keyboard interactions
| Key | Action |
|---|---|
| ← / → / ↑ / ↓ | Navigate between day cells within the grid. |
| Enter / Space | Select the focused day, month or year. |
| PageUp / PageDown | Move to the previous / next month without leaving the day grid. |
| Home / End | Jump to the first / last day of the current week row. |
| Escape | Close the picker (when used inside DatePickerField). |
Notes
- The day grid uses role="grid" with role="gridcell" for each day. Disabled days have aria-disabled="true" and are skipped in keyboard navigation.
- Each day button has an aria-label with the full date string (e.g. "15 juin 2026") for screen reader users.
- View-change transitions (OrigamFade) are disabled under prefers-reduced-motion: reduce.
Foundation
Design tokens
Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.
- dimension40px
- Day button size (width and height).
- colorvar(--origam-color__action--primary---bg)
- Selected day button background.
- colorvar(--origam-color__surface---overlay)
- Days in range background (range mode).
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Single date
Date range
With actions
Ecosystem
Family
Components from the same folder that share conventions and often compose together.
DatePickerControls
Navigation bar with prev/next and view-mode (month/year) toggle buttons.
DatePickerHeader
Coloured header strip showing the selected date or month.
DatePickerMonth
Day-grid view for picking a date within the current month.
DatePickerMonths
Month-grid view for picking a month within the current year.
DatePickerYears
Scrollable year list for picking a year.