Skip to content
Porcelana

DatePicker & Calendar

Date picker with a month grid, disabled days, localised formatting and keyboard navigation.

Inputs

Example

November 2026
Example.tsx
import { Calendar, DatePicker, Field } from "@porcelana/ui";

export default function Example() {
  return (
    <div style={{ display: "grid", gap: 24 }}>
      <div style={{ maxWidth: 360 }}>
        <Field label="Start date">
          <DatePicker disabledDays={{ dayOfWeek: [0, 6] }} placeholder="Pick a weekday" />
        </Field>
      </div>
      <Calendar mode="single" />
    </div>
  );
}

Import

Import
import { DatePicker, Calendar } from "@porcelana/ui";
import "@porcelana/ui/styles.css"; // once, at your app root

Props

Generated from the TypeScript types. Standard HTML attributes are passed through and not listed.

DatePicker

PropTypeDefaultDescription
aria-labelstring–Defines a string value that labels the current element. @see aria-labelledby.
defaultValueDate | nullnullInitial value when uncontrolled.
disabledboolean–Prevents interaction and dims the control.
disabledDaysMatcher | Matcher[]–Days that cannot be picked (react-day-picker matchers).
endMonthDate–Latest navigable month.
idstring–Element id. Generated automatically when omitted.
localestring–BCP 47 locale for the trigger text. Defaults to the browser locale.
onOpenChange((open: boolean) => void)–Called when the open state changes.
onValueChange((date: Date | null) => void)–Called with the new value.
openboolean–Controlled open state. Use with onOpenChange.
placeholderstringPick a dateHint shown when there is no value.
startMonthDate–Earliest navigable month.
type"button" | "submit" | "reset"–Button type (defaults to "button").
valueDate | null–Controlled value. Use with onValueChange.

Calendar

Month grid with 44px day cells, keyboard navigation and today marker. Monday-first by default.

PropTypeDefaultDescription
animateboolean–Animate navigating between months. @since 9.6.0 @see https://daypicker.dev/docs/navigation#animate
aria-labelstring–The aria-label attribute to add to the container element. @since 9.4.1 @see https://daypicker.dev/guides/accessibility
aria-labelledbystring–The aria-labelledby attribute to add to the container element. @since 9.11.0 @see https://daypicker.dev/guides/accessibility
autoFocusboolean–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. @see https://daypicker.dev/guides/accessibility#autofocus
broadcastCalendarboolean–Display the weeks in the month following the broadcast calendar. Setting this prop will ignore {@link weekStartsOn} (always Monday) and {@link showOutsideDays} will default to true. @since 9.4.0 @see https://daypicker.dev/docs/localization#broadcast-calendar @see https://en.wikipedia.org/wiki/Broadcast_calendar
captionLayout"label" | "dropdown" | "dropdown-months" | "dropdown-years"–Show dropdowns to navigate between months or years. - `label`: Displays the month and year as a label. Default value. - `dropdown`: Displays dropdowns for both month and year navigation. - `dropdown-months`: Displays a dropdown only for the month navigation. - `dropdown-years`: Displays a dropdown only for the year navigation. **Note:** By default, showing the dropdown will set the {@link startMonth} to 100 years ago and {@link endMonth} to the end of the current year. You can override this behavior by explicitly setting `startMonth` and `endMonth`. @see https://daypicker.dev/docs/customization#caption-layouts
classNamestring–Class name to add to the root element.
classNames(Partial<ClassNames> & Partial<DeprecatedUI<string>>)–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. @see https://daypicker.dev/docs/styling
componentsPartial<CustomComponents>–Change the components used for rendering the calendar elements. @see https://daypicker.dev/guides/custom-components
dateLibPartial<DateLib>–Replace the default date library with a custom one. Experimental: not guaranteed to be stable (may not respect semver). @since 9.0.0 @experimental
defaultMonthDate–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 {@link month} and {@link onMonthChange}. @defaultValue The current month @see https://daypicker.dev/docs/navigation
dirstring–The text direction of the calendar. Use `ltr` for left-to-right (default) or `rtl` for right-to-left. @see https://daypicker.dev/docs/translation#rtl-text-direction
disabledMatcher | Matcher[]–Apply the `disabled` modifier to the matching days. Disabled days cannot be selected when in a selection mode is set. @see https://daypicker.dev/docs/selection-modes#disabled @see https://daypicker.dev/docs/selection-modes#disabled @see https://daypicker.dev/docs/selection-modes#disabled
disableNavigationboolean–Disable the navigation between months. This prop won't hide the navigation: to hide the navigation, use {@link hideNavigation}. @see https://daypicker.dev/docs/navigation#disablenavigation
endMonthDate–The latest month to end the month navigation. @since 9.0.0 @see https://daypicker.dev/docs/navigation#start-and-end-dates
excludeDisabledboolean–When `true`, the range will reset when including a disabled day. @since 9.0.2 @see https://daypicker.dev/docs/selection-modes#exclude-disabled @since 9.0.2
firstWeekContainsDate1 | 4–The day of January that is always in the first week of the year. @see https://daypicker.dev/docs/localization#first-week-contains-date
fixedWeeksboolean–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. @see https://daypicker.dev/docs/customization#fixed-weeks
footerReactNode–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. @see https://daypicker.dev/guides/accessibility#footer
formattersPartial<Formatters>–Formatters used to format dates to strings. Use this prop to override the default functions. @see https://daypicker.dev/docs/translation#custom-formatters
fromDateDate–@private @deprecated This prop has been removed. Use `hidden={{ before: date }}` instead. @see https://daypicker.dev/docs/navigation#start-and-end-dates
fromMonthDate–@private @deprecated This prop has been renamed to `startMonth`. @see https://daypicker.dev/docs/navigation#start-and-end-dates
fromYearnumber–@private @deprecated Use `startMonth` instead. E.g. `startMonth={new Date(year, 0)}`. @see https://daypicker.dev/docs/navigation#start-and-end-dates
hiddenMatcher | Matcher[]–Apply the `hidden` modifier to the matching days. Will hide them from the calendar. @see https://daypicker.dev/guides/custom-modifiers#hidden-modifier
hideNavigationboolean–Hide the navigation buttons. This prop won't disable the navigation: to disable the navigation, use {@link disableNavigation}. @since 9.0.0 @see https://daypicker.dev/docs/navigation#hidenavigation
hideWeekdaysboolean–Hide the row displaying the weekday row header. @since 9.0.0
idstring–A unique id to add to the root element.
initialFocusboolean–@private @deprecated This prop will be removed. Use {@link autoFocus } instead.
ISOWeekboolean–Use ISO week dates instead of the locale setting. Setting this prop will ignore `weekStartsOn` and `firstWeekContainsDate`. @see https://daypicker.dev/docs/localization#iso-week-dates @see https://en.wikipedia.org/wiki/ISO_week_date
labelsPartial<Labels>–Labels creators to override the defaults. Use this prop to customize the aria-label attributes in DayPicker. @see https://daypicker.dev/docs/translation#aria-labels
langstring–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.
localePartial<DayPickerLocale>–The locale object used to localize dates. Pass a locale from `react-day-picker/locale` to localize the calendar. @example import { es } from "react-day-picker/locale"; <DayPicker locale={es} /> @defaultValue enUS - The English locale default of `date-fns`. @see https://daypicker.dev/docs/localization @see https://github.com/date-fns/date-fns/tree/main/src/locale for a list of the supported locales
maxnumber–The maximum number of selectable days. The maximum number of days to include in the range.
minnumber–The minimum number of selectable days. The minimum number of days to include in the range.
mode"single" | "multiple" | "range"–Enable the selection of a single day, multiple days, or a range of days. @see https://daypicker.dev/docs/selection-modes
modifiersRecord<string, Matcher | Matcher[]>–Add modifiers to the matching days. @example const modifiers = { weekend: { dayOfWeek: [0, 6] }, // Match weekends holiday: [new Date(2023, 11, 25)] // Match Christmas }; <DayPicker modifiers={modifiers} /> @see https://daypicker.dev/guides/custom-modifiers
modifiersClassNamesModifiersClassNames–Change the class name for the day matching the `modifiers`. @see https://daypicker.dev/guides/custom-modifiers
modifiersStylesModifiersStyles–Change the class name for the day matching the {@link modifiers}. @see https://daypicker.dev/guides/custom-modifiers
monthDate–The month displayed in the calendar. As opposed to `defaultMonth`, use this prop with `onMonthChange` to change the month programmatically. @see https://daypicker.dev/docs/navigation
navLayout"around" | "after"–Adjust the positioning of the navigation buttons. - `around`: Displays the buttons on either side of the caption. - `after`: Displays the buttons after the caption. This ensures the tab order matches the visual order. If not set, the buttons default to being displayed after the caption, but the tab order may not align with the visual order. @since 9.7.0 @see https://daypicker.dev/docs/customization#navigation-layouts
noncestring–A cryptographic nonce ("number used once") which can be used by Content Security Policy for the inline `style` attributes.
noonSafeboolean–Keep calendar math at noon in the configured {@link timeZone} to avoid historical second-level offsets drifting dates across midnight. This prop sets the time of the dates to noon (12:00). @since 9.13.0 @experimental @see https://daypicker.dev/localization/setting-time-zone#noonsafe
numberOfMonthsnumber–The number of displayed months. @defaultValue 1 @see https://daypicker.dev/docs/customization#multiplemonths
numeralsNumerals–The numeral system to use when formatting dates. - `latn`: Latin (Western Arabic) - `arab`: Arabic-Indic - `arabext`: Eastern Arabic-Indic (Persian) - `deva`: Devanagari - `beng`: Bengali - `guru`: Gurmukhi - `gujr`: Gujarati - `orya`: Oriya - `tamldec`: Tamil - `telu`: Telugu - `knda`: Kannada - `mlym`: Malayalam @defaultValue `latn` Latin (Western Arabic) @see https://daypicker.dev/docs/translation#numeral-systems
onDayBlurDayEventHandler<FocusEvent<Element, Element>>–Event handler when a day is blurred.
onDayClickDayEventHandler<MouseEvent<Element, MouseEvent>>–Event handler when a day is clicked.
onDayFocusDayEventHandler<FocusEvent<Element, Element>>–Event handler when a day is focused.
onDayKeyDownDayEventHandler<KeyboardEvent<Element>>–Event handler when a key is pressed on a day.
onDayKeyPressDayEventHandler<KeyboardEvent<Element>>–@private @deprecated Use a custom `DayButton` component instead.
onDayKeyUpDayEventHandler<KeyboardEvent<Element>>–@private @deprecated Use a custom `DayButton` component instead.
onDayMouseEnterDayEventHandler<MouseEvent<Element, MouseEvent>>–Event handler when the mouse enters a day.
onDayMouseLeaveDayEventHandler<MouseEvent<Element, MouseEvent>>–Event handler when the mouse leaves a day.
onDayPointerEnterDayEventHandler<PointerEvent<Element>>–@private @deprecated Use a custom `DayButton` component instead.
onDayPointerLeaveDayEventHandler<PointerEvent<Element>>–@private @deprecated Use a custom `DayButton` component instead.
onDayTouchCancelDayEventHandler<TouchEvent<Element>>–@private @deprecated Use a custom `DayButton` component instead.
onDayTouchEndDayEventHandler<TouchEvent<Element>>–@private @deprecated Use a custom `DayButton` component instead.
onDayTouchMoveDayEventHandler<TouchEvent<Element>>–@private @deprecated Use a custom `DayButton` component instead.
onDayTouchStartDayEventHandler<TouchEvent<Element>>–@private @deprecated Use a custom `DayButton` component instead.
onMonthChangeMonthChangeEventHandler–Event fired when the user navigates between months. @see https://daypicker.dev/docs/navigation#onmonthchange
onNextClickMonthChangeEventHandler–Event handler when the next month button is clicked. @see https://daypicker.dev/docs/navigation
onPrevClickMonthChangeEventHandler–Event handler when the previous month button is clicked. @see https://daypicker.dev/docs/navigation
onSelectOnSelectHandler<Date> | OnSelectHandler<Date> | OnSelectHandler<Date[]> | OnSelectHandler<...> | OnSelectHandler<...> | OnSelectHandler<...> | undefined–Event handler when a day is selected. Event handler when days are selected. Event handler when the selection changes. Event handler when a range is selected.
onWeekNumberClickany–Event handler when a week number is clicked. @private @deprecated Use a custom `WeekNumber` component instead. @see https://daypicker.dev/docs/customization#showweeknumber
pagedNavigationboolean–Paginate the month navigation displaying the `numberOfMonths` at a time. @see https://daypicker.dev/docs/customization#multiplemonths
requiredboolean–Whether the selection is required. @see https://daypicker.dev/docs/selection-modes
resetOnSelectboolean–When `true`, clicking a day starts a new range if there is no current start date or if a range is already complete. In those cases, the clicked day becomes the start of the new range. When `required` is `false`, clicking the same day of a single-day range clears the selection. When `true`, clicking a day starts a new range if there is no current start date or if a range is already complete. In those cases, the clicked day becomes the start of the new range. @since 9.14 @see https://daypicker.dev/selections/range-mode#reset-selection @since 9.14 @see https://daypicker.dev/selections/range-mode#reset-selection
reverseMonthsboolean–Render the months in reversed order (when {@link numberOfMonths} is set) to display the most recent month first. @see https://daypicker.dev/docs/customization#multiplemonths
reverseYearsboolean–Reverse the order of years in the dropdown when using `captionLayout="dropdown"` or `captionLayout="dropdown-years"`. @since 9.9.0 @see https://daypicker.dev/docs/customization#caption-layouts
role"dialog" | "application"–The role attribute to add to the container element. @since 9.4.1 @see https://daypicker.dev/guides/accessibility
selectedDate | Date[] | DateRange–The selected date. The selected dates. The selected range.
showOutsideDaysbooleantrueShow the outside days (days falling in the next or the previous month). **Note:** when a {@link broadcastCalendar} is set, this prop defaults to true. @see https://daypicker.dev/docs/customization#outside-days
showWeekNumberboolean–Show the week numbers column. Weeks are numbered according to the local week index. @see https://daypicker.dev/docs/customization#showweeknumber
startMonthDate–The earliest month to start the month navigation. @since 9.0.0 @see https://daypicker.dev/docs/navigation#start-and-end-dates
styleCSSProperties–Style to apply to the root element.
styles(Partial<Styles> & Partial<DeprecatedUI<CSSProperties>>)–Change the inline styles of the HTML elements. @see https://daypicker.dev/docs/styling
timeZonestring–The time zone (IANA or UTC offset) to use in the calendar (experimental). See [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for the possible values. @since 9.1.1 @see https://daypicker.dev/localization/setting-time-zone
titlestring–Add a `title` attribute to the container element.
toDateDate–@private @deprecated This prop has been removed. Use `hidden={{ after: date }}` instead. @see https://daypicker.dev/docs/navigation#start-and-end-dates
todayDate–The today’s date. Default is the current date. This date will get the `today` modifier to style the day. @see https://daypicker.dev/guides/custom-modifiers#today-modifier
toMonthDate–@private @deprecated This prop has been renamed to `endMonth`. @see https://daypicker.dev/docs/navigation#start-and-end-dates
toYearnumber–@private @deprecated Use `endMonth` instead. E.g. `endMonth={new Date(year, 0)}`. @see https://daypicker.dev/docs/navigation#start-and-end-dates
useAdditionalDayOfYearTokensboolean–Enable `YY` and `YYYY` for day of year tokens when formatting or parsing dates. @see https://date-fns.org/docs/Unicode-Tokens
useAdditionalWeekYearTokensboolean–Enable `DD` and `DDDD` for week year tokens when formatting or parsing dates. @see https://date-fns.org/docs/Unicode-Tokens
weekStartsOn0 | 1 | 2 | 3 | 4 | 5 | 61The index of the first day of the week (0 - Sunday). Overrides the locale's default. @see https://daypicker.dev/docs/localization#first-date-of-the-week

Accessibility

  • The calendar is a labelled grid; arrows move by day and week, Enter picks.
  • Focus lands on the selected day (or today) when it opens.
  • Disabled days are announced and can't be picked.

Mobile

  • 44px day cells and navigation buttons.