Skip to main content

Calendar

Preview

A calendar component that allows users to select a date or a range of dates. Use mode="single" to let a user select a single date, or mode="range" to let a user select a range.

When to use

  • Pick one date or a range of dates from a month grid with previous and next month buttons. The calendar has no text entry.
  • Reveal the calendar from a trigger: compose it inside a Popover.

Popover

Compose the Calendar inside a Popover to reveal it from a trigger.

Range

Use mode="range" to let a user select a start and end date.

Range with multiple months

Use numberOfMonths to render more than one month at a time.

Hidden days

Pass an array of dates to hidden to remove them from the calendar.

Disabled days

Pass an array of dates to disabled to prevent them from being selected.

Server rendering

Calendar highlights today's date and prefixes that day's aria-label with Today,. If you omit today, DayPicker reads the clock during render, once on the server and again in the browser. If the two clocks or time zones disagree on the date, the highlight and the label land on different days. React then reports a hydration mismatch. If you also omit month and defaultMonth, the grid opens on different months.

Under SSR, pass today and defaultMonth (or month) from one date the request produced, such as a loader value. timeZone aligns the zone only, not the clock, so it doesn't replace today.

Accessibility

The month grid, the day buttons, and the previous/next month buttons come from React DayPicker, which names them and handles arrow-key navigation between days. The navigation buttons carry mantle's IconButton ghost styling, including its focus ring.

API Reference

The Calendar is built on top of React DayPicker and accepts every DayPicker prop. Mantle changes these:

PropTypeDefaultDescription
mode"single" | "multiple" | "range"Selection mode. "range" also rounds the ends of a selected range.
showOutsideDays?booleanfalseWhether days from the previous and next month fill the first and last week. DayPicker defaults to true; mantle defaults to false.
className?stringClasses for the calendar root, merged with classNames.root.
classNames?Partial<ClassNames>Per-element class overrides. Mantle sets its own defaults for every key; yours merge over them, and root merges with className.

@ngrok/mantle/calendar also exports the DateRange type for mode="range".

Data AttributeValueDescription
data-slot"calendar"The calendar root.