# Calendar > A month or week grid for choosing a date, several dates or a range Status: beta. Added in Components 2.16.0. A month or week grid for choosing a date, several dates or a range. ## Import ```tsx import { Calendar } from '@oztix/roadie-components/calendar' ``` ## Examples ### Default Calendar opens on the selected month, or on today's. Every value is a plain ISO date string such as `'2026-11-27'`, never a `Date`. Today moves on at midnight in `timeZone`. Server HTML may be read on a later day, so the server leaves today unmarked, and a calendar with nothing else to place its month renders an empty six-week frame until the browser fills it in. Pass `today`, `month`, `defaultMonth` or a selection to render it in full on the server. The month's name sits at the start of the header and both arrows sit at the end. On a touch screen, swipe the days sideways to turn the month, or drag them with a mouse or pen; a press that barely moves still chooses the day. The days follow the finger with the next month's days coming in beside them, while the weekday row and the month's name stay still, and the swipe runs the other way in a right-to-left page. With several months in a row, their days move as one strip. On a vertical calendar the next month's name comes up with its days, in the gap above them. The arrows and `Page Up` and `Page Down` slide the days the same way. The shown and incoming pages move together in one motion, and the month and its name change as the slide ends. With `Shift`, or in week view, `Page Up` and `Page Down` skip past the page beside, so they turn at once. A month picked from the selects shows at once and slides in. Arrow keys that cross into the next month turn it straight away, so focus never sits on a day that is sliding. When the reader prefers reduced motion, every turn is instant. ```tsx function Default() { const [date, setDate] = useState(null) return (

Selected: {date ?? 'none'}

) } render() ``` ### Variants `captionLayout='dropdown'` swaps the month name for month and year selects, for dates far from today such as a date of birth. `startMonth` and `endMonth` limit how far either way they reach. ```tsx ``` ### States ```tsx {/* Selected */} {/* Disabled */} ``` ### With a range `mode='range'` takes `{ start, end }`. The first press sets `start` and leaves `end` null, and the days between preview as the pointer or focus moves. `min` and `max` limit the length in days, both ends counted. Days that would break them dim. Pressing one keeps the start and announces the rule, such as "Ranges can be up to 14 days", so say the rule in visible text near the calendar too. Pressing the start again makes a one-day range, or drops the start when `min` is more than 1, and `Escape` drops it. For a range in a form or a toolbar, with presets and typed dates, use [DateRangePicker](https://ticketsolutionsptyltd.github.io/roadie/components/date-range-picker.md). ```tsx function Range() { const [range, setRange] = useState({ start: null, end: null }) return (

Choose up to 14 days.

{range.start ?? '…'} to {range.end ?? '…'}

) } render() ``` ### With several dates `mode='multiple'` takes a list of dates and keeps it in order. ```tsx ``` ### With past dates disabled `disabled` takes matchers: a date, a list of dates, `{ start, end }`, `{ before }`, `{ after }`, `{ dayOfWeek }` with 1 for Monday, or a function of the date. Disabled days can still be focused, so keyboard users can move past them. ```tsx const today = plainDateOf(new Date(), viewerTimeZone()) render() ``` ### With modifiers `modifiers` names sets of days with the same matchers. Each name becomes a data attribute on its days, so `hasSession` renders `data-has-session` to style. Here Lampshade Disco at Kazoo Hollow Room runs on the bold nights, and the struck-through night is sold out. ```tsx const sessions = ['2026-11-05', '2026-11-06', '2026-11-07', '2026-11-12', '2026-11-13', '2026-11-14'] const soldOut = ['2026-11-07'] render(
!sessions.includes(date), ...soldOut]} className='**:data-has-session:font-bold **:data-sold-out:line-through' />

Bold nights have a show. Struck-through nights are sold out.

) ``` ### With a preview range `previewRange` draws days as a neutral band, shaped like a chosen range but not chosen. Use it for dates someone has typed but not yet taken, as the records search does. A chosen range draws over it. ```tsx ``` ### With two months `numberOfMonths` shows months side by side where they fit and stacks them where they don't. Both arrows sit together at the top end, and each moves the set one month. Side by side, the months turn sideways and their days move as one strip. Stacked, they turn up and down as one column, as with `direction='vertical'`: the arrows point up and down, and a finger swipes up for the next month. The first month's name sits by the arrows, one weekday row holds still beneath them, and the months below it slide with their names. The calendar switches back as soon as the months fit side by side again. ```tsx ``` ### With scrolling months `layout='scroll'` stacks the months in a list that scrolls, as on a phone, under one row of weekdays that stays pinned. There are no arrows: it opens on `month`, the selection or today, and adds months as it nears either end or the keyboard moves past them. A new `month` scrolls the list to it, and in a box that scrolls `onMonthChange` reports the month at the top as it scrolls. Put it in a `ScrollArea`, as here, or in a `Drawer` or `Pane` body, which already scroll, rather than a box with its own native scrollbar. To run the pinned row to the edges, pad the calendar and pull its `calendar-weekdays` slot out by the same amount, as here. Pickers use it in their phone drawer. ```tsx ``` ### With vertical paging `direction='vertical'` turns the months up and down: the arrows point up and down, and a finger swipes up for the next month. Over the days, a finger no longer scrolls the page up and down, so use it only where the calendar has the screen to itself. For one continuous list of months, use `layout='scroll'` instead. ```tsx ``` ### With a week view `view='week'` shows one week as a row of larger days, and the arrows and a swipe turn a week at a time. It suits choosing a session in the coming days. `views` lists the views the reader can switch between. With both, a toggle group of "Week" and "Month" sits beside the title, or above the months when there are several. Where the calendar is narrow, as on a phone, it shows only their icons and the week's title shortens its month names, such as "Oct to Nov 2026". Switching eases between the two: the week's days glide between their places, the other weeks grow out of it or fold into it as they fade, and the height follows. With reduced motion it switches at once. Month view opens on the month of the selected day (or a range's start) in the week, then the focused day's, then the month holding most of the week. Week view opens on the week of the selected or focused day in the month, today's, or else its first week. Use `defaultView` to open on one, or `view` and `onViewChange` to control it. ```tsx function Week() { const [date, setDate] = useState(null) return (

Selected: {date ?? 'none'}

) } render() ``` ### With day content `getDayContent` adds content under a day's number, such as a price or how many sessions are left, in the month and the week alike. Return null for a plain day, not an empty element. Every day becomes a tile so the columns line up, days with content are filled, and tiles grow to fit, so a long line wraps rather than spills. Tiles stay up to 64px wide, or 80px in a week. A disabled day with content is struck through, so here sold-out nights read as unavailable while nights outside the run stay plain. The content describes the day to screen readers, so give a mark like a dot some words too. ```tsx const nights = { '2026-10-28': { price: 29, left: 2 }, '2026-10-29': { price: 29, left: 4 }, '2026-10-30': { soldOut: true }, '2026-10-31': { price: 35, left: 1 }, '2026-11-01': { price: 35, left: 3 }, '2026-11-04': { price: 29, left: 4 }, '2026-11-05': { price: 29, left: 2 }, '2026-11-06': { price: 35, left: 1 }, '2026-11-07': { soldOut: true }, '2026-11-08': { price: 35, left: 4 }, '2026-11-11': { price: 29, left: 4 }, '2026-11-12': { price: 29, left: 3 }, '2026-11-13': { price: 39, left: 4 }, '2026-11-14': { price: 39, left: 4 }, '2026-11-15': { price: 39, left: 2 } } function nightContent(date) { const night = nights[date] if (!night) return null if (night.soldOut) return 'Sold out' return ( <> ${night.price}