Usage
import { Calendar } from "@voila.dev/ui/calendar";The bare month grid, always visible and always taking the space of a month. That is the reason to choose it: a booking screen where the dates are the page wants the grid open, not a field that hides it. Anywhere the date is one field among many, reach for DatePicker — it wraps this same grid in a popover and gives you a labelled trigger for free. On a phone, NativeDatePicker hands the job to the OS, which draws a better picker than anything in the page.
Built on React DayPicker, so its mode, disabled,
locale and the rest apply unchanged.
Recipes
A range, in one grid
mode="range" swaps the selection model: selected becomes { from, to } and
the grid tracks the hover edge as the range is drawn. The DateRange type comes
from @voila.dev/ui/date-picker, which is where the range-shaped pickers live.
Weekends and past dates ruled out
disabled takes DayPicker's matchers, and they compose — { before: … } with
{ dayOfWeek: [0, 6] } blocks the past and weekends. Blocking a day in the
grid is not the same as validating it on submit: a matcher stops the click, it
does not stop a value arriving from a query string.
API
Calendar.Root
| Prop | Type | Default | |
|---|---|---|---|
locale | string | — | BCP-47 locale (e.g. "fr-FR") applied to the month, weekday, and day labels. |
navButtonVariant | "brand" | "default" | "destructive" | "ghost" | "highlight" | "link" | "outline" | "primary" | "secondary" | "ghost" | Button variant for the previous/next month arrows. |
animate | boolean | — | Animate navigating between months. |
aria-label | string | — | The aria-label attribute to add to the container element. |
aria-labelledby | string | — | The aria-labelledby attribute to add to the container element. |
autoFocus | boolean | — | When a selection mode is set, DayPicker will focus the first selected day (if set) or today's date (if not disabled). Use this prop when you need to focus DayPicker after a user action, for improved accessibility. |
broadcastCalendar | boolean | — | Display the weeks in the month following the broadcast calendar. Setting this prop will ignore weekStartsOn (always Monday) and showOutsideDays will default to true. |
captionLayout | "dropdown" | "dropdown-months" | "dropdown-years" | "label" | "label" | Show dropdowns to navigate between months or years. Note: By default, showing the dropdown will set the startMonth
to 100 years ago and endMonth to the end of the current year. You
can override this behavior by explicitly setting startMonth and
endMonth. |
className | string | — | Class name to add to the root element. |
classNames | Partial<ClassNames> | — | Change the class names used by DayPicker. Use this prop when you need to change the default class names — for example, when importing the style via CSS modules or when using a CSS framework. |
components | Partial<CustomComponents> | — | Change the components used for rendering the calendar elements. |
dateLib | Partial<DateLib> | — | Replace the default date library with a custom one. Experimental: not guaranteed to be stable (may not respect semver). |
defaultMonth | Date | — | The initial month to show in the calendar. Use this prop to let DayPicker control the current month. If you need to set the month programmatically, use month and onMonthChange. |
dir | string | — | The text direction of the calendar. Use ltr for left-to-right (default)
or rtl for right-to-left. |
disabled | Matcher[] | Matcher | — | Apply the disabled modifier to the matching days. Disabled days cannot be
selected when in a selection mode is set. |
disableNavigation | boolean | — | Disable the navigation between months. This prop won't hide the navigation: to hide the navigation, use hideNavigation. |
endMonth | Date | — | The latest month to end the month navigation. |
firstWeekContainsDate | 1 | 4 | — | The day of January that is always in the first week of the year. |
fixedWeeks | boolean | — | Display always 6 weeks per each month, regardless of the month’s number of weeks. Weeks will be filled with the days from the next month. |
footer | ReactNode | — | Add a footer to the calendar, acting as a live region. Use this prop to communicate the calendar's status to screen readers. Prefer strings over complex UI elements. |
formatters | Partial<Formatters> | — | Formatters used to format dates to strings. Use this prop to override the default functions. |
hidden | Matcher[] | Matcher | — | Apply the hidden modifier to the matching days. Will hide them from the
calendar. |
hideNavigation | boolean | — | Hide the navigation buttons. This prop won't disable the navigation: to disable the navigation, use disableNavigation. |
hideWeekdays | boolean | — | Hide the row displaying the weekday row header. |
id | string | — | A unique id to add to the root element. |
ISOWeek | boolean | — | Use ISO week dates instead of the locale setting. Setting this prop will
ignore weekStartsOn and firstWeekContainsDate. |
labels | Partial<Labels> | — | Labels creators to override the defaults. Use this prop to customize the aria-label attributes in DayPicker. |
lang | string | — | Add the language tag to the container element. When omitted, DayPicker uses the active locale code (locale.code). Set
this prop to override the language tag. |
mode | "multiple" | "range" | "single" | — | Enable the selection of a single day, multiple days, or a range of days. |
modifiers | Record<string, Matcher[] | Matcher | undefined> | — | Add modifiers to the matching days. |
modifiersClassNames | ModifiersClassNames | — | Change the class name for the day matching the modifiers. |
modifiersStyles | ModifiersStyles | — | Change the class name for the day matching the modifiers. |
month | Date | — | The month displayed in the calendar. As opposed to defaultMonth, use this prop with onMonthChange to change
the month programmatically. |
navLayout | "after" | "around" | — | Adjust the positioning of the navigation buttons. If not set, DayPicker preserves its legacy layout, but the tab order may
not align with the visual order when using captionLayout="dropdown". |
nonce | string | — | A cryptographic nonce ("number used once") which can be used by Content
Security Policy for the inline style attributes. |
noonSafe | boolean | — | Keep calendar math at noon in the configured timeZone to avoid historical second-level offsets drifting dates across midnight. This prop sets the time of the dates to noon (12:00). |
numberOfMonths | number | — | The number of displayed months. |
numerals | Numerals | — | The numeral system to use when formatting dates. |
onDayBlur | DayEventHandler<FocusEvent<Element, Element>> | — | Event handler when a day is blurred. |
onDayClick | DayEventHandler<MouseEvent<Element, MouseEvent>> | — | Event handler when a day is clicked. |
onDayFocus | DayEventHandler<FocusEvent<Element, Element>> | — | Event handler when a day is focused. |
onDayKeyDown | DayEventHandler<KeyboardEvent<Element>> | — | Event handler when a key is pressed on a day. |
onDayMouseEnter | DayEventHandler<MouseEvent<Element, MouseEvent>> | — | Event handler when the mouse enters a day. |
onDayMouseLeave | DayEventHandler<MouseEvent<Element, MouseEvent>> | — | Event handler when the mouse leaves a day. |
onMonthChange | MonthChangeEventHandler | — | Event fired when the user navigates between months. |
onNextClick | MonthChangeEventHandler | — | Event handler when the next month button is clicked. |
onPrevClick | MonthChangeEventHandler | — | Event handler when the previous month button is clicked. |
pagedNavigation | boolean | — | Paginate the month navigation displaying the numberOfMonths at a time. |
required | boolean | — | Whether the selection is required. |
reverseMonths | boolean | — | Render the months in reversed order (when numberOfMonths is set) to display the most recent month first. |
reverseYears | boolean | — | Reverse the order of years in the dropdown when using
captionLayout="dropdown" or captionLayout="dropdown-years". |
role | "application" | "dialog" | — | The role attribute to add to the container element. |
showOutsideDays | boolean | true | Show the outside days (days falling in the next or the previous month). Note: when a broadcastCalendar is set, this prop defaults to true. |
showWeekNumber | boolean | — | Show the week numbers column. Weeks are numbered according to the local week index. |
startMonth | Date | — | The earliest month to start the month navigation. |
style | CSSProperties | — | Style to apply to the root element. |
styles | Partial<Styles> | — | Change the inline styles of the HTML elements. |
timeZone | string | — | The time zone (IANA or UTC offset) to use in the calendar (experimental). See Wikipedia for the possible values. |
title | string | — | Add a title attribute to the container element. |
today | Date | — | The today’s date. Default is the current date. This date will get the
today modifier to style the day. |
useAdditionalDayOfYearTokens | boolean | — | Enable YY and YYYY for day of year tokens when formatting or parsing
dates. |
useAdditionalWeekYearTokens | boolean | — | Enable DD and DDDD for week year tokens when formatting or parsing
dates. |
weekStartsOn | 0 | 1 | 2 | 3 | 4 | 5 | 6 | — | The index of the first day of the week (0 - Sunday). Overrides the locale's default. |
Plus the DOM props of the element it renders. Source: calendar/components/calendar-root.tsx.
Calendar.DayButton
| Prop | Type | Default | |
|---|---|---|---|
locale | string | — | BCP-47 tag used to format the data-day attribute on each cell. |
day | CalendarDay | required | The day to render. |
modifiers | Modifiers | required | The modifiers to apply to the day. |
Plus the DOM props of the element it renders. Source: calendar/components/calendar-day-button.tsx.
The individual day cell, exposed so a custom components.DayButton can build on
it. You rarely render it directly.