# Coming from FullCalendar Source: https://super-calendar.afonsojramos.me/coming-from-fullcalendar A concept map for porting a FullCalendar app to super-calendar, on React Native or the web. [FullCalendar](https://fullcalendar.io) is the reference event calendar on the web, and its API shaped several of super-calendar's props on purpose. This is not a drop-in swap: FullCalendar is plugin-based and web-only, super-calendar is a single component with two renderers. But the concepts line up closely, which makes a port tractable, and it is the practical answer to the long-standing ask for [a FullCalendar-style calendar on React Native](https://github.com/fullcalendar/fullcalendar/issues/7076). Use this page as the concept map. If you are moving to React Native, also read [Migrating from calendar-kit](/migrating-from-calendar-kit) for the RN setup steps (Reanimated, Gesture Handler); on the web use `@super-calendar/dom`. > [!NOTE] > > Checked against FullCalendar v7 in mid-2026. Verify option names against your installed version, > and note that some FullCalendar features are Premium. ## No plugins FullCalendar assembles a calendar from plugins (`@fullcalendar/daygrid`, `timegrid`, `interaction`, `resource-timeline`, `rrule`). super-calendar has no plugin system: month, week/day, schedule, year, resources, drag, and recurrence are all in the package. You pick a view with `mode`, not `plugins` + `initialView`. ## Concept map | FullCalendar | super-calendar | | - | - | | `plugins` + `initialView: "dayGridMonth"` | `mode="month"` | | `timeGridWeek` / `timeGridDay` | `mode="week"` / `mode="day"` | | `listWeek` | `mode="schedule"` | | `multiMonthYear` | `mode="year"` | | `resourceTimeline` (Premium) | the `ResourceTimeline` component (free) | | controlled via `datesSet` + API | controlled `date` + `onChangeDate` / `onChangeDateRange` | | `events` (array / feed / function source) | `events` array of `CalendarEvent` (fetch feeds yourself) | | `eventClick` | `onPressEvent` | | `dateClick` / `select` | `onPressCell` / `onPressDay` / `onCreateEvent` | | `editable` | `onDragEvent` (enables move + resize) | | `eventStartEditable` / `eventDurationEditable` | `eventStartEditable` / `eventDurationEditable` (same names) | | `eventOverlap={false}` | `eventOverlap={false}` (same name) | | `businessHours` / `eventConstraint` | `businessHours` (shading) + return `false` from `onDragEvent` | | `eventContent` / `eventDidMount` | `renderEvent` (a component) | | `rrule` plugin | `expandRecurringEvents` + a `recurrence` field | | `timeZone` | `timeZone` prop + `eventsInTimeZone` (display-only) | | background events (`display: "background"`) | background events (an event with `display: "background"`) | | `headerToolbar` | build your own controls (or `headerComponent`) | The editable, overlap, and business-hours names match on purpose, so those parts of a port are close to a rename. ## The port prompt Copy this into a coding agent working in your repo. ```text theme={null} You are porting a FullCalendar app to super-calendar. On the web import from `@super-calendar/dom`; on React Native import from `@super-calendar/native` and add its peers (Reanimated v4, Gesture Handler, Worklets, @legendapp/list v3, date-fns) with at the root. Rewrite the calendar rather than renaming plugins. 1. Replace the element with a single . Map views: dayGridMonth -> "month", timeGridWeek -> "week", timeGridDay -> "day", listWeek -> "schedule", multiMonthYear -> "year". Resource timeline becomes the separate component. 2. Hold the anchor date in state; replace datesSet/goto API calls with setting `date` and reading `onChangeDate` / `onChangeDateRange`. 3. Events: pass an array of { start: Date, end: Date, title, ...your fields }. Convert ISO strings to Date. For URL/Google/iCal feeds, fetch them yourself (use `parseICalendar` for iCal text). Keep your own event objects for saving. 4. Handlers: eventClick -> onPressEvent; dateClick/select -> onPressCell / onPressDay / onCreateEvent; editable -> onDragEvent(event, start, end); eventStartEditable / eventDurationEditable / eventOverlap keep their names; enforce eventConstraint/businessHours by returning false from onDragEvent. 5. Rendering: eventContent/eventDidMount -> a `renderEvent` component. 6. Recurrence: replace the rrule plugin with `expandRecurringEvents(events, rangeStart, rangeEnd)` over the visible range, or set `recurrence` on events. 7. There is no built-in header toolbar; render your own prev/next/title controls and drive `date` / `mode`. Then run the app and verify views, event placement, drag/resize, and recurrence. ``` ## What differs * **No built-in toolbar.** FullCalendar ships `headerToolbar`; super-calendar leaves chrome to you (a built-in toolbar is on the roadmap). * **Event sources.** FullCalendar fetches URL / Google / iCal feeds for you. super-calendar takes a plain array; fetch feeds yourself, and use [`parseICalendar`](/guides/ical) for iCal text. * **Time zones** are display-only via [`eventsInTimeZone`](/guides/time-zones), not a native Temporal/IANA model. * **Breadth.** FullCalendar has a larger ecosystem (print, more sources, Premium timeline/scheduler). super-calendar is leaner and MIT-only, and its resource timeline is free. The upside: one calendar that runs on web **and** React Native from the same props, with drag, recurrence, and resources built in. See the [comparison](/comparison) and [Why super-calendar](/why). # Coming from react-big-calendar Source: https://super-calendar.afonsojramos.me/coming-from-react-big-calendar A concept map for porting a react-big-calendar app to super-calendar, on the web or React Native. [react-big-calendar](https://github.com/jquense/react-big-calendar) is a popular web React calendar. super-calendar covers the same month/week/day/agenda model with a similar controlled component, so a port is mostly mapping props, plus picking up things react-big-calendar leaves to you (drag, recurrence). It is not a drop-in swap: there is no `localizer`, dates are `Date` objects, and drag is built in rather than an add-on. On the web import from `@super-calendar/dom`; on React Native import from `@super-calendar/native` (and add its native peers). This page is the concept map; hand the [prompt](#the-port-prompt) to your agent for the mechanical part. > [!NOTE] > > Checked against react-big-calendar 1.x in mid-2026. Verify prop names against your installed > version. ## Concept map | react-big-calendar | super-calendar | | - | - | | `localizer` (`dateFnsLocalizer`, `momentLocalizer`) | no localizer; `locale` (a date-fns `Locale`) + `weekStartsOn` | | `events` + `startAccessor` / `endAccessor` / `titleAccessor` | `events` with `start` / `end` / `title` (Dates) | | `view` / `onView` | `mode` (`month` `week` `day` `3days` `custom` `schedule`) | | `date` / `onNavigate` | `date` / `onChangeDate` | | `views={["month","week","day","agenda"]}` | switch `mode`; `agenda` maps to `schedule` | | `onSelectEvent` | `onPressEvent` | | `onSelectSlot` (`selectable`) | `onPressCell` / `onPressDay` / `onCreateEvent` | | `withDragAndDrop` HOC + `onEventDrop` / `onEventResize` | `onDragEvent(event, start, end)` (built in) | | `components={{ event, toolbar, ... }}` | `renderEvent`, `headerComponent`, `renderTimeGridHeader` | | `eventPropGetter` / `dayPropGetter` | `eventCellStyle` / `calendarCellStyle` (+ `classNames` on web) | | `min` / `max` (time-grid bounds) | `minHour` / `maxHour` | | `messages` (label strings) | `locale`, plus `moreLabel` / `allDayLabel` | | (no recurrence) | `expandRecurringEvents` + a `recurrence` field | ## Before and after react-big-calendar: ```tsx theme={null} import { Calendar, dateFnsLocalizer } from "react-big-calendar"; const localizer = dateFnsLocalizer(/* ... */); open(event)} onSelectSlot={(slot) => create(slot.start, slot.end)} selectable />; ``` super-calendar (web renderer): ```tsx theme={null} import { useState } from "react"; import { Calendar } from "@super-calendar/dom"; function Schedule({ events }) { const [date, setDate] = useState(() => new Date()); return ( open(event)} onCreateEvent={(start, end) => create(start, end)} /> ); } ``` ## The port prompt Copy this into a coding agent working in your repo. ```text theme={null} You are porting a react-big-calendar app to super-calendar. On the web import from `@super-calendar/dom`; on React Native import from `@super-calendar/native` (add Reanimated v4, Gesture Handler, Worklets, @legendapp/list v3, date-fns and wrap the app in ). Rewrite the calendar element rather than renaming a localizer. 1. Drop the `localizer`. Pass `weekStartsOn` and, for non-English, a date-fns `Locale` as `locale`. Ensure event `start`/`end` are Date objects (not the accessor strings); fold startAccessor/endAccessor/titleAccessor into the event shape { start, end, title, ...yourFields }. 2. Replace `view`/`onView` with `mode`, and `date`/`onNavigate` with `date` + `onChangeDate`. Map views: month->"month", week->"week", day->"day", agenda->"schedule". 3. Handlers: onSelectEvent -> onPressEvent; onSelectSlot -> onCreateEvent (drag) and onPressCell/onPressDay (tap). 4. Drag/resize: remove the withDragAndDrop HOC and onEventDrop/onEventResize; add onDragEvent(event, start, end) (return false to reject). Set eventOverlap={false} to block overlaps declaratively. 5. Custom rendering: components.event -> a `renderEvent` component; components.toolbar -> your own controls or `headerComponent`; eventPropGetter/ dayPropGetter -> eventCellStyle/calendarCellStyle (and per-slot `classNames` on the web renderer). 6. Time-grid bounds min/max -> minHour/maxHour. 7. Recurrence: react-big-calendar has none; if you expanded rules yourself, use `expandRecurringEvents(events, rangeStart, rangeEnd)` over the visible range. 8. Note react-big-calendar treats the end date as exclusive; check all-day and multi-day spans render as you expect and adjust the end if needed. Then run the app and verify views, selection, event placement, and drag. ``` ## What differs * **Drag is built in.** react-big-calendar is unopinionated and ships drag as the `withDragAndDrop` add-on; super-calendar has [move/resize/create](/guides/dragging) in the box, with declarative `eventOverlap` and editability flags. * **Exclusive end dates.** react-big-calendar treats `end` as exclusive; confirm multi-day and all-day events land right after the port. * **No localizer object.** Formatting comes from date-fns via `locale`. * **It also runs on React Native** from the same props, which react-big-calendar does not. See the [comparison](/comparison), [Dragging](/guides/dragging), and [Recurring events](/guides/recurring-events). # Comparison Source: https://super-calendar.afonsojramos.me/comparison How super-calendar compares to other React Native calendar libraries, feature by feature. This is the head-to-head a React Native developer actually faces: the RN calendar libraries you might reach for instead. Every one of them is good at what it targets, so the table below is a map of trade-offs, not a scoreboard. For the "coming from the web" case (FullCalendar, react-big-calendar) see [Coming from FullCalendar](/coming-from-fullcalendar) and [Coming from react-big-calendar](/coming-from-react-big-calendar). > [!NOTE] > > Checked mid-2026 against each project's current docs. Libraries move fast, so verify anything > load-bearing against the version you install. ## Feature matrix | Capability | super-calendar | react-native-big-calendar | @howljs/calendar-kit | react-native-calendars | flash-calendar | | - | - | - | - | - | - | | Month grid | ✅ | ✅ | ❌ (top request) | ✅ dots | ✅ picker | | Week / day / N-day time grid | ✅ | ✅ | ✅ | ✅ timeline | ❌ | | Agenda / schedule list | ✅ | ✅ | ❌ | ✅ | ❌ | | Resource timeline | ✅ | ❌ | ✅ | ⚠️ timeline | ❌ | | True multi-day spanning bars | ✅ | ⚠️ per-day chip | ✅ time grid | ❌ dots | ❌ | | Drag to move / resize / create | ✅ | ❌ (declined upstream) | ✅ | ❌ | ❌ | | Recurring events (RRULE) | ✅ helper | ❌ | ✅ | ❌ | ❌ | | Time-zone display | ✅ | ❌ | ✅ per-event | ❌ | ❌ | | Overlapping events | ✅ side-by-side | ⚠️ stacked | ✅ | n/a | n/a | | Date selection / range picker | ✅ | ❌ | ❌ | ✅ | ✅ | | Virtualized, snap-paged views | ✅ | ❌ | ✅ | ⚠️ | ✅ | | Accessibility (labels + keyboard) | ✅ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | | Theming / custom render | ✅ | ✅ | ✅ | ✅ | ✅ | | Dark-mode preset | ✅ `darkTheme` | ❌ bring your own | ✅ | ⚠️ | ⚠️ | | Also runs on the web (same API) | ✅ | ⚠️ partial | ❌ | ❌ | ❌ | | License | MIT | MIT | MIT | MIT | MIT | Legend: ✅ built in · ➕ official add-on · ⚠️ partial or with caveats · ❌ not available. ## What each one is best at Picking the right tool matters more than a row of checkmarks: * **[react-native-big-calendar](https://github.com/acro5piano/react-native-big-calendar)** has the lightest footprint here (`dayjs` + `calendarize`, no Reanimated or Gesture Handler). If you want month/week/day/agenda without gestures, virtualization, or drag, it is the simpler dependency story. super-calendar is its spiritual successor, so the `` API is close: see [Migrating from react-native-big-calendar](/migrating-from-big-calendar). * **[@howljs/calendar-kit](https://github.com/howljs/react-native-calendar-kit)** has an excellent time grid with pinch-zoom, haptics, resources, RRULE, and per-event time zones. Its gap is the month and agenda views (the month view is its most-requested feature). If you only need day/week scheduling, it is a strong choice. See [Migrating from calendar-kit](/migrating-from-calendar-kit). * **[react-native-calendars](https://github.com/wix/react-native-calendars)** (Wix) is the most established, with a mature marked-dates month, agenda, and timeline. It has no event drag, recurrence, or all-day spanning bars (it marks days with dots), and the project has been quieter lately. * **[flash-calendar](https://github.com/MarceloPrado/flash-calendar)** is a fast, tiny infinite-scroll date picker built on FlashList. It has no event model, so it is a picker rather than an event calendar. It inspired our `MonthList`. ## Why super-calendar The axis that sets it apart is one calendar model that runs on **React DOM and React Native** from the same API, with events, drag-and-drop, recurrence, time zones, and resources built in and free. If you are web-only, a mature web library like [FullCalendar](https://fullcalendar.io) may still suit you better; if you only need a native date picker, flash-calendar is leaner. Reach for super-calendar when you want a full event calendar that behaves the same across platforms. See also [Why super-calendar](/why) for the high-level positioning and the [dom vs native comparison](/reference/renderers) for what differs between the two renderers. # Live demo Source: https://super-calendar.afonsojramos.me/demo Try the React Native, React DOM, and Solid renderers on the web. One example app per renderer, hosted on GitHub Pages. Everything here runs the real library, no mocks. > [tab] React Native > > The [`examples/native`](https://github.com/afonsojramos/super-calendar/tree/main/examples/native) > app, exported for the web with react-native-web. This is the same code that > runs on iOS and Android. > > [super-calendar React Native web demo](https://demo.super-calendar.afonsojramos.me/) > [tab] react-dom > > The [`examples/web`](https://github.com/afonsojramos/super-calendar/tree/main/examples/web) > app: the [`@super-calendar/dom`](/guides/dom) renderer with no React Native > runtime. It adds web-only surfaces to try, including the date picker, > `MonthList`, a fully Tailwind-styled month, the resource timeline, and > iCalendar import/export. > > [super-calendar react-dom web demo](https://demo.super-calendar.afonsojramos.me/dom/) > [tab] Solid 2 > > The [`examples/solid`](https://github.com/afonsojramos/super-calendar/tree/main/examples/solid) > app uses the [`@super-calendar/solid`](/guides/solid) renderer. > Choose a calendar mode, scrolling months, resources, or the event feed with > **View**. Try dragging events, selecting dates with the pickers, and switching > themes. In the resources view, toggle **Vertical resources** to change the > layout. > > [super-calendar Solid 2 web demo](https://demo.super-calendar.afonsojramos.me/solid/) ## Things to try in the React demos * **Switch modes** with the tabs: month, week, 3-day, day, schedule. * **Pinch / Ctrl-scroll** on the week or day grid to zoom the hours. * **Click-drag an event** vertically to change its time, horizontally to move it to another day. Drag the evening gig down past the end of its day and it continues on the next one. The exam is "locked": its drop is rejected and it snaps back. * **Drag the grip** at an event's bottom edge to resize it. * **Click-drag empty space** to create an event; press **Escape** mid-drag to cancel. * **Right-click an event** for the context menu (move / delete). * Note the shaded hours: business hours are 9–5 on weekdays, and weekends read as closed. > [!NOTE] > > On native, dragging starts on a long-press (so taps and scrolls aren't hijacked); on the web it > starts after a small drag, so a plain click still selects. See [Dragging & > creating](/guides/dragging) and [Web](/guides/web). # Accessibility Source: https://super-calendar.afonsojramos.me/guides/accessibility Screen-reader labels, move and resize actions, keyboard navigation, and reduced motion. Every renderer ships accessible defaults: every event, day cell, and day-column header carries a full label and role out of the box, and moving or resizing an event has an alternative to dragging. On React Native it is a set of screen-reader actions; on the web it is a dialog of buttons that works with a keyboard, a single click, or a tap. ## Labels Day cells announce the full date, today, selection state, and how many events they hold ("Friday, 17 July 2026, today, 3 events"). Events announce their title and time range; all-day events say so instead of a time. Override the event announcement with `eventAccessibilityLabel`: ```tsx theme={null} isAllDay ? `${event.title}, all day` : `${event.title} at ${event.start.toLocaleTimeString()}` } /* ... */ /> ``` ### Translating the labels The date part of each label follows `locale`. The words around it come from `labels`, so pass translations to localize them. Keys you omit stay in English (`defaultCalendarLabels`). Define the object outside the component, or memoize it, so the views don't re-render on every pass: ```tsx theme={null} import { pt } from "date-fns/locale"; import type { CalendarLabels } from "@super-calendar/native"; const labels: Partial = { today: "hoje", selected: "selecionado", unavailable: "indisponível", hasEvents: "tem eventos", eventCount: (count) => (count === 1 ? "1 evento" : `${count} eventos`), moreEvents: (count) => `mais ${count} eventos`, allDay: "todo o dia", allDayEvent: "todo o dia", timeRange: (start, end) => `${start} até ${end}`, close: "Fechar", moveLater: (minutes) => `Adiar ${minutes} minutos`, moveEarlier: (minutes) => `Antecipar ${minutes} minutos`, extend: (minutes) => `Prolongar ${minutes} minutos`, shorten: (minutes) => `Encurtar ${minutes} minutos`, moveToNextPage: (days, mode) => mode === "week" ? "Mover para a semana seguinte" : days === 1 ? "Mover para o dia seguinte" : `Mover para os ${days} dias seguintes`, moveToPreviousPage: (days, mode) => mode === "week" ? "Mover para a semana anterior" : days === 1 ? "Mover para o dia anterior" : `Mover para os ${days} dias anteriores`, moveToResource: (title) => `Mover para ${title}`, editEvents: "Editar eventos", eventActions: (title) => title ? `Mover ou redimensionar ${title}` : "Mover ou redimensionar evento", }; ; ``` | Key | Default | Where it appears | | - | - | - | | `today`, `selected`, `unavailable` | "today", "selected", "unavailable" | Day cells and day-column headers. | | `hasEvents` | "has events" | Year-view days. | | `eventCount(count)` | "3 events" | Month-view day cells. | | `moreEvents(count)` | "3 more events" | The "+N more" control. | | `close` | "Close" | The "+N more" popover backdrop (native) and the web actions dialog's close button. | | `allDay` | "all-day" | The time-grid gutter text, with `showAllDayLabel`. | | `allDayEvent` | "all day" | An all-day event's label. `allDayLabel` wins when set. | | `timeRange(start, end)` | "09:00 to 10:00" | A timed event's label. | | `moveLater`, `moveEarlier`, `extend`, `shorten` | "Move 15 minutes later", "Extend by 15 minutes" | Move and resize actions. | | `moveToNextPage(days, mode)`, `moveToPreviousPage(days, mode)` | "Move to next week" | Time-grid move actions. | | `moveToResource(title)` | "Move to Room A" | `ResourceTimeline` lane moves. | | `editEvents` | "Edit events" | The web event chooser button. Optional. | | `eventActions(title)` | "Move or resize Planning" | The web event choice and actions dialog. Optional. | | `eventChangeRejected` | "This change is not allowed." | Rejected edits in the web actions dialog. Optional. | The `", "` separator and the word order are fixed. To word a whole event label differently, use `eventAccessibilityLabel`. ## Screen-reader actions (React Native) Dragging is a gesture, so draggable events expose the same operations as [accessibility actions](https://reactnative.dev/docs/accessibility#accessibility-actions): VoiceOver and TalkBack users pick "Move 15 minutes later/earlier" or "Extend/Shorten by 15 minutes" from the actions rotor, and the change commits through the same `onDragEvent` path as a gesture. The step follows `dragStepMinutes`. Time-grid events and [ResourceTimeline](/guides/resource-timeline) bars both expose them whenever `onDragEvent` is set. Translate their names with [`labels`](#translating-the-labels). ## Move and resize actions (web) In React DOM and Solid, **Edit events** opens a list of the visible events you can move or resize in `TimeGrid` and either `ResourceTimeline` orientation. The chooser shows each event's date and time, plus its resource on the board. Long lists scroll while each choice keeps its full title and dates visible. Titles without spaces wrap within the choice or dialog. Its buttons have separate targets, even when events overlap or the calendar is narrow. Choosing an event never activates it or starts a drag. Opening the chooser focuses its first event. Use the arrow keys, Home, End, or Tab to navigate its choices; Escape closes it and focuses **Edit events**. Choose an event to open a modal dialog named after the event ("Move or resize Planning"). The dialog is centered in the viewport, shows the event's time, and lists native buttons: * **Move 15 minutes later / earlier** and **Extend / Shorten by 15 minutes**, stepping by `dragStepMinutes`. * **Move to next / previous week** (or day, or N days) in `TimeGrid`. * **Move to** the neighbouring lanes in `ResourceTimeline`, named after the resources. Each button commits through the same path as a drop. `onDragEvent` receives the proposed start and end (and the target resource on the board), the same bounds a drag produces. `eventOverlap={false}`, `draggable: false`, `startEditable`, and `durationEditable` apply as they do to a drag. A shorten that would leave the event below one step is marked unavailable with `aria-disabled`. Returning `false` from `onDragEvent` leaves the event where it was. A rejected change shows `labels.eventChangeRejected` in a polite status region, including overlap rejections. Repeated rejections update the region again; an accepted edit clears it. The calendar stays controlled. After an accepted change, the dialog follows the unique new event you render in its place (same title, new times, and new lane on the board), so you can press **Move later** several times in a row. Other event objects must keep their references for this default matching to work. For full data refreshes, pass `getEventId` to web `Calendar`, `TimeGrid`, or `ResourceTimeline`. Return a stable string or number that uniquely identifies each event in `events`. For recurring data, identify each occurrence, not its series. Numeric `0` and string `"0"` are distinct IDs. The dialog follows that ID when objects, titles, times, or lanes change, and actions use the latest event. Without `getEventId`, a full refresh closes the dialog. The dialog closes if the event disappears, its identity is ambiguous, its lane goes away, or editing is turned off. With `getEventId`, removing the getter or providing missing, invalid, or duplicate IDs also closes it. IDs must be strings or numbers. The live description includes both dates for multi-day events and, on the board, the resource. When the dialog opens, focus moves to its first action. The arrow keys, Home, and End move between the actions alongside Tab. PageUp and PageDown do not page the calendar behind the dialog. **Escape**, the **Close** button, or a click on the backdrop closes it and returns focus to **Edit events**. If that control is gone, focus returns to the calendar. Style the parts with `eventActionsTrigger` (the chooser button), `eventActionsList` (the event list), `eventActions` (the dialog), and `eventAction` (each button) slots, and translate the words with [`labels`](#translating-the-labels): ```tsx theme={null} import { useState } from "react"; import { type CalendarEvent, TimeGrid } from "@super-calendar/dom"; export function EditableWeek() { const [events, setEvents] = useState[]>([ { id: "planning", title: "Planning", start: new Date(2026, 6, 15, 9), end: new Date(2026, 6, 15, 10), }, ]); return ( mode="week" date={new Date(2026, 6, 15)} events={events} getEventId={(event) => event.id} onDragEvent={(event, start, end) => { setEvents((current) => current.map((e) => (e.id === event.id ? { ...e, start, end } : e))); }} labels={{ eventActions: (title) => `Edit times for ${title}`, eventChangeRejected: "Choose another time.", }} classNames={{ eventActionsTrigger: "rounded-full bg-white shadow" }} /> ); } ``` ## Keyboard (web) * **Paging** — on react-native-web the left/right arrow keys page the month and time-grid views (the schedule scrolls instead); the dom renderer pages with PageUp/PageDown when `onChangeDate` is wired. * **`keyboardDayNavigation`** (dom `MonthView` / `MonthList`) — arrow keys move between day cells, Enter/Space selects. * **`keyboardEventNavigation`** (dom `TimeGrid`) — Up/Down move through a day's events by time, Left/Right jump to the nearest event in the adjacent day, Home/End reach the first/last, Enter/Space activate. Navigation is additive: every event stays in the Tab order. * **Date pickers**: opening a `DatePicker` or `DateRangePicker` moves focus to the selected day (or today, or the first available day in that month). If that month has no available days, focus moves to the popover panel. Arrow keys move between days; **Escape** closes the popover and returns focus to the field. Picking a date or completing a range also returns focus to the field. ## Reduced motion On React Native the time grid honours the OS reduce-motion setting: its one animated snap (recentring after a cell press) becomes an instant jump. The month pager's page transitions never animate programmatic jumps in the first place. Reanimated drives the remaining transitions on the UI thread, so nothing relies on JS-thread timing. ## Automated checks The shared browser tests run [axe](https://github.com/dequelabs/axe-core) against the month list, time grid, resource timelines, date pickers, and the actions dialog in Chromium, Firefox, and WebKit, together with keyboard and focus assertions. These checks catch common semantic and focus problems. They do not replace testing with the screen readers your users rely on. ## Custom renderers A custom `renderEvent` receives `accessibilityActions` / `onAccessibilityAction` in its args on native; spread them onto your pressable root so screen-reader move/resize keeps working (the built-in renderers do this for you). On the web, the event chooser also works with custom `renderEvent` content, so your renderer does not need to add controls. # Date & range picker Source: https://super-calendar.afonsojramos.me/guides/date-picker Shipped DatePicker and DateRangePicker inputs, or compose your own on the web. > [!NOTE] > > These are **web renderer** (`@super-calendar/dom` and `@super-calendar/solid`) components. The > examples below use React. For signals, see the [Solid picker > example](/guides/solid#add-date-pickers). On React Native, compose a picker from `MonthList` + > `useDateRange` (the same primitives shown below). super-calendar ships two controlled popover inputs, `DatePicker` and `DateRangePicker`. Both wrap `MonthList`, so you can build your own if you need different chrome. ## DatePicker A single date, controlled by `value` / `onChange`: ```tsx theme={null} import { useState } from "react"; import { DatePicker } from "@super-calendar/dom"; function Field() { const [value, setValue] = useState(null); return ; } ``` ## DateRangePicker A start/end range. Each pick advances the selection (start, then end), and the popover closes once both are set: ```tsx theme={null} import { useState } from "react"; import { type DateRange, DateRangePicker } from "@super-calendar/dom"; function Field() { const [range, setRange] = useState(null); return ; } ``` Both accept `minDate` / `maxDate` / `isDateDisabled`, a `placeholder`, `disabled`, a `formatLabel` for the trigger text, and the calendar `theme`. Opening the popover moves focus to the selected day (the range start for `DateRangePicker`), or to today, or to the first available day in that month. If the month has no available days, focus moves to the popover panel. Arrow keys move between days. They close on outside-click and `Escape`. `Escape`, picking a date, and completing a range return focus to the trigger. Setting `disabled` closes an open popover and prevents date changes, without moving focus to the disabled field. Re-enabling the field leaves the popover closed until you open it again. ## Styling The `theme` applies to both the picker chrome and its calendar. Theme changes update the open calendar, and per-slot `styles` take precedence over theme values. The picker chrome has its own slots (`trigger`, `popover`, `footer`, `clear`), and any [calendar slot](/guides/styling) you pass through `classNames` reaches the popover's `MonthList`: ```tsx theme={null} ``` ## Roll your own If you want fully custom chrome, wrap `MonthList` yourself and drive it with `useDateRange` (range) or `selectedDates` (single). The building blocks: ```tsx theme={null} import { MonthList, useDateRange } from "@super-calendar/dom"; function CustomRange() { const { range, onPressDate } = useDateRange(); return ( ); } ``` Add your own trigger/popover and the two behaviours every popover needs (outside-click and `Escape` to close). See the **field** tab on the [live demo](/demo). # react-dom renderer Source: https://super-calendar.afonsojramos.me/guides/dom A pure react-dom calendar with no React Native runtime, from @super-calendar/dom. `@super-calendar/dom` renders the calendar with real DOM elements. There is no React Native and no react-native-web in the tree: it builds on the same headless core as the native package and on Legend List's DOM renderer. Reach for it when your app is web-only, or web-first, and you don't want to pull a React Native runtime into the bundle. If you already ship a React Native app and want one codebase that also runs in the browser, use [`@super-calendar/native` on react-native-web](/guides/web) instead. ## Install ```bash npm theme={null} npm install @super-calendar/dom react react-dom @legendapp/list date-fns ``` ```bash pnpm theme={null} pnpm add @super-calendar/dom react react-dom @legendapp/list date-fns ``` `react`, `react-dom`, `@legendapp/list`, and `date-fns` are peer dependencies, so they resolve to the single copy your app already uses. ## What it renders | Export | Renders | | - | - | | `Calendar` | Batteries-included: picks the view from `mode` (month, schedule, grid). | | `TimeGrid` | A day/week/N-day time grid with an all-day lane and a now line. | | `Agenda` | A day-grouped, scrolling list of events: the schedule view. | | `MonthList` | A scrolling, virtualized month: a date picker, or a calendar with events. | | `MultiWeekView` | Consecutive full weeks with event bars and no hourly slots. | | `MonthView` | A single month grid: compact picker, or a calendar with event chips. | `Calendar` mirrors the React Native component's API across every view, including `mode="schedule"` (the `Agenda` list). You can also drop down to the individual views. The selection hook (`useDateRange`) and grid helpers (`useMonthGrid`, `buildMonthGrid`, `layoutDayEvents`) are re-exported from the core, so you import everything from one place. The month views take an optional `events` prop: pass it (even `[]`) and the grid switches from the compact picker look to a calendar layout with event chips and a "+N more" overflow; omit it for the picker. `TimeGrid` supports `businessHours` shading, `timeslots`, a bounded hour window (`minHour`/`maxHour`, plus `hideHours` to drop the hour axis), `showWeekNumber` (with `weekNumberPrefix`), `onPressCell`, drag-to-create (`onCreateEvent`), and drag-to-move/resize (`onDragEvent`, which can return `false` to reject a drop). Creating on empty space is pointer-only (drag to sweep out a range); see [Keyboard navigation](#keyboard-navigation) for how focus moves. On empty time-grid space, a touch tap calls `onPressCell` from the column's click. A swipe or cancelled contact does not create an event. Mouse and pen retain drag-to-create behavior. This also applies through DOM `Calendar`. The drag-to-create preview stays within the visible hours of the pressed column, with its border inside the column. See [Drag to create](/guides/dragging#drag-to-create). Pass `renderCreateGhost` to `TimeGrid`, `Calendar`, or `ResourceTimeline` to draw a draft inside that preview. It receives the live `start` and `end` that `onCreateEvent` would get on release. See [Show a draft in the preview](/guides/dragging#show-a-draft-in-the-preview). ## The Calendar wrapper The quickest start mirrors the native component: pick a `mode` and pass events. ```tsx theme={null} import { Calendar, type CalendarEvent } from "@super-calendar/dom"; const events: CalendarEvent[] = [ { title: "Standup", start: new Date(2026, 5, 23, 9, 0), end: new Date(2026, 5, 23, 9, 30) }, ]; export function App() { return ( console.log(event.title)} /> ); } ``` Switch `mode` to `"month"` for a month grid with event chips, `"schedule"` for a day-grouped agenda list, or `"day"` / `"3days"` / `"custom"` (with `numberOfDays`) for the time grid. Custom rendering splits by view: `renderTimeEvent` for the time grid, `renderMonthEvent` for month chips, and `renderScheduleEvent` for agenda rows. ## Multi-week rows Use `mode="multiweek" numberOfWeeks={3}` on `Calendar`, or render `MultiWeekView` for one window. The default is two weeks, starting with the week containing `date`. Month slots and `renderMonthEvent` also style this mode. PageUp/PageDown advance by the chosen week count. Set `height` on `Calendar` to scroll the rows inside that viewport. See [multi-week grids](/guides/views#multi-week-grids). ## Schedule (agenda) `mode="schedule"` (or the `Agenda` component directly) renders a scrolling list of events grouped under a date header per day, sorted by start. It does not window by `date`: it shows exactly the `events` you pass, so you control the range. Each row defaults to a time + title; override it with `renderScheduleEvent`. ```tsx theme={null} import { Agenda, type CalendarEvent } from "@super-calendar/dom"; const events: CalendarEvent[] = [ { title: "Standup", start: new Date(2026, 5, 23, 9, 0), end: new Date(2026, 5, 23, 9, 30) }, { title: "Lunch", start: new Date(2026, 5, 23, 12, 0), end: new Date(2026, 5, 23, 13, 0) }, ]; console.log(event.title)} onPressDay={(day) => console.log("header", day)} />; ``` ## A time grid and a range picker ```tsx theme={null} import { useMemo } from "react"; import { type CalendarEvent, MonthList, TimeGrid, useDateRange } from "@super-calendar/dom"; const events: CalendarEvent[] = [ { title: "Standup", start: new Date(2026, 5, 23, 9, 0), end: new Date(2026, 5, 23, 9, 30) }, { title: "Design review", start: new Date(2026, 5, 23, 9, 15), end: new Date(2026, 5, 23, 10, 30), }, ]; export function App() { const today = useMemo(() => new Date(), []); const { range, onPressDate, reset } = useDateRange({ minDate: today }); return ( <> ); } ``` `TimeGrid` and `MonthList` take an explicit `height` because they virtualize and scroll inside that box. Everything else (events, selection, week start) matches the native API, since both renderers share the core types. ## Selection Selection works as in the native [Date selection](/guides/selection) guide: `useDateRange` returns `range` and an `onPressDate` handler, and you pass `selectedRange` (or `selectedDates`) plus `minDate` / `maxDate` / `isDateDisabled` to `MonthList`. Selection is driven by clicking days; the react-dom renderer does not implement pointer drag-select. ## Keyboard navigation Tab moves through **events only**. Empty day columns (time grid) and empty day cells (month) are not tab stops, so keyboard focus lands on each event in turn rather than stopping on every blank cell. Events are buttons: Enter or Space activates them (`onPressEvent`). This is a deliberate default. The alternative, making every empty cell focusable, turns a week into seven tab stops before the first event and a month into dozens. Creating on empty space stays pointer-only (drag to sweep out a range); if you want a keyboard way to add an event, render your own "New event" button. Three cases add richer keyboard navigation: * The **date picker** (`MonthList` or `MonthView` rendered without `events`) is always keyboard-navigable: one roving tab stop per month, arrow keys move the focus, Enter selects the day. Date selection is the whole point there. * **Month with events**, opt in with `keyboardDayNavigation` to add the same roving day focus on top of the event chips, so Enter on a focused day opens it (`onPressDay`). It is off by default. * **Time grid with events**, opt in with `keyboardEventNavigation` to add arrow-key movement between events: Up/Down step through a day by time, Left/Right jump to the nearest event in the adjacent day, Home/End go to the day's first/last event, and Enter/Space activate. This is additive: every event stays individually tabbable, so screen-reader users keep full access and the arrow keys are a convenience for sighted keyboard users. Off by default. The day-column headers always carry a full-date label for screen readers, whether or not they're interactive. ```tsx theme={null} import { Calendar } from "@super-calendar/dom"; // Time grid where arrow keys move a roving focus between events. ; ``` ```tsx theme={null} import { Calendar, type CalendarEvent } from "@super-calendar/dom"; const events: CalendarEvent[] = [ { title: "Standup", start: new Date(2026, 5, 23, 9, 0), end: new Date(2026, 5, 23, 9, 30) }, ]; // Month view where arrow keys also move a roving day focus (Enter opens the day). console.log("open day", day)} />; ``` `keyboardDayNavigation` and `keyboardEventNavigation` are web-only concerns, so they exist on the react-dom renderer only. The React Native renderer pages with the arrow keys on react-native-web instead. ### Paging with the keyboard Pass `onChangeDate` and the focused calendar pages with **PageDown** / **PageUp**: a month in `month`, a week in `schedule`, otherwise the view's day span. It's controlled, so update `date` in response (the same handler you'd wire to your own prev/next buttons). Omit `onChangeDate` and the keys fall through untouched. ```tsx theme={null} ``` ## Theming The DOM theme is a flat object of colors plus a few metrics, separate from the React Native `CalendarTheme` (which carries `TextStyle`/`ViewStyle`). Both derive their colors from the same core tokens, so the palettes match and the [color-token list](/guides/theming#color-tokens) applies here too (just flat, not nested under `colors`). ```tsx theme={null} import { darkDomTheme, mergeDomTheme, TimeGrid } from "@super-calendar/dom"; // mergeDomTheme(overrides, base?) — base defaults to defaultDomTheme. const brand = mergeDomTheme({ selectedBackground: "#7c3aed", cellHeight: 56 }); ; // or pass `theme={darkDomTheme}` for dark mode ``` The theme recolours everything at once. To hand a **specific part** of a view to Tailwind or your own CSS — with `data-*` state variants like `data-[today]:` — use the per-slot `classNames` / `styles` props. See [Styling with Tailwind & CSS](/guides/styling). See it running on the [live demo](/demo) and in the [`examples/web`](https://github.com/afonsojramos/super-calendar/tree/main/examples/web) Vite app. # Drag, resize & create events Source: https://super-calendar.afonsojramos.me/guides/dragging Move, resize, reschedule across days, and create events by dragging. Everything here is opt-in: pass the relevant handler and update your own event state in response. Move, resize, and create work on the week/day grid; move and create also work on the month grid (see [On the month grid](#on-the-month-grid)), where a drag moves an event by whole days rather than by time. The year grid sweeps out day ranges too (see [On the year grid](#on-the-year-grid)). ## Move and resize Pass `onDragEvent` to make events draggable. Move an event (**long-press** it on native, **click-drag** it on web), or **drag the grip** at its **bottom edge to change the end** or its **top edge to change the start**. Drag **vertically to change the time, horizontally to move it to another day** (within the visible range). New `start`/`end` are snapped to `dragStepMinutes` (default 15). ```tsx theme={null} setEvents((prev) => prev.map((e) => (e.id === event.id ? { ...e, start, end } : e))) } /> ``` ### DOM held presses On the DOM time grid, touch and pen wait for a 300 ms hold within 8 px before dragging. A tap calls `onPressEvent` from the event's own click. A vertical swipe that starts on an event or resize grip scrolls the grid. During a held drag, scrolling stops until release or cancellation. Mouse dragging starts immediately. Set `touchDragDelay` (milliseconds) and `touchDragThreshold` (pixels) on DOM `Calendar` or `TimeGrid` to adjust the hold. Movement, pointer cancellation, another finger, navigation, or unmount cancels a pending hold. An additional contact on an event or resize grip cannot start a replacement hold or take over an active drag. These options apply to event gestures, not empty-slot or month interactions. In the multi-week web grid, keep the `events` input stable when `onDragStart` updates unrelated UI state. With recurrence or `timeZone`, a new array rebuilds the displayed events and cancels a held move. See [keep event data stable](/guides/events#keep-event-data-stable). ### Move an event past midnight A move keeps its duration, so dragging an event **down past the end of the day** lets its end run into the next one: the box cuts off at the day boundary and the remainder previews at the top of the next column, exactly where the committed event will render. The **start** stays in the day you dropped it on (it stops one `dragStepMinutes` step before the end of the day), so a move to a different day is still the horizontal drag. `onDragEvent` then receives a `start` and `end` on different dates. Dragging any day's segment of the resulting multi-day event moves the whole thing, so it never gets clipped to the day you grabbed. All visible segments preview the move together, including segments that enter a new column. Both dates shift together to preserve the event's duration. For example, moving a Tuesday 17:00 to Thursday 21:00 event one day earlier previews Monday 17:00 to Wednesday 21:00, whichever segment you grab. Use a resize grip to change just the start or end. ### Hide the drag handle By default a small grip shows at each draggable event's bottom edge. Set `showDragHandle={false}` to hide that indicator while keeping drag-to-move and drag-to-resize fully working, so events stay editable without the visual marker. You can toggle `showDragHandle` after mounting; native time-grid grips update without replacing the `events` array. ```tsx theme={null} setEvents((prev) => prev.map((e) => (e.id === event.id ? { ...e, start, end } : e))) } /> ``` ### Colour an event's grips Set `dragHandleColor` on an event to override its resize grip colour in `@super-calendar/native`. This applies to both time-grid grips and to the resource timeline's grip in either orientation. Omit it to use `theme.colors.eventText`. Choose a colour that contrasts with the event's background. ```tsx theme={null} import type { CalendarEvent } from "@super-calendar/native"; const events: CalendarEvent[] = [ { title: "Blocked time", start: new Date(2026, 5, 23, 9), end: new Date(2026, 5, 23, 10), dragHandleColor: "#ffffff", }, ]; ``` `showDragHandle={false}` still hides the time-grid grips. The DOM renderer's resize targets have no visible grips, so this field does not change their appearance. ### Lock specific events `onDragEvent` makes **every** event draggable, which is the right default: most calendars let you reschedule anything. When a few events must never move (a confirmed booking, an event someone else owns, a holiday), set `draggable: false` on those events. They keep their normal appearance and still respond to taps, they just can't be picked up or resized. Nothing else needs to change. ```tsx theme={null} const events = [ { id: "1", title: "Standup", start, end }, { id: "2", title: "Driving test", start, end, draggable: false }, // can't be moved ]; ``` Reach for this when an event can *never* move, so you don't offer a drag that only snaps back. To refuse a move for some targets but not others (see below), keep the event draggable and reject the specific drop instead. (For an event that shouldn't respond to taps either and should read as unavailable, use `disabled: true`, which also dims it.) ### Allow only move or only resize Split the two with `startEditable` (can be moved) and `durationEditable` (can be resized), per event or grid-wide via `eventStartEditable` / `eventDurationEditable` (both default `true`). A `draggable: false` event stays fully locked regardless. ```tsx theme={null} const events = [ { id: "1", title: "Standup", start, end, durationEditable: false }, // move, don't resize { id: "2", title: "Focus", start, end, startEditable: false }, // resize, don't move ]; // Or a grid-wide default (e.g. resize is off everywhere): ; ``` ### Reject a drop Return `false` from `onDragEvent` to refuse a particular placement — the event snaps back to where it started (on the time grid a cross-week drop snaps the view back too, so the rejection is visible). Use it for rules that depend on where the event lands: overlaps, out-of-bounds slots, or business-hours limits. The library is expo-free, so fire your own feedback (a haptic, a toast) right where you reject. ```tsx theme={null} import * as Haptics from "expo-haptics"; onDragEvent={(event, start, end) => { if (overlapsAnother(event, start, end)) { void Haptics.notificationAsync(Haptics.NotificationFeedbackType.Error); return false; } setEvents((prev) => prev.map((e) => (e.id === event.id ? { ...e, start, end } : e))); }} ``` The overlap case is common enough that it's built in: set `eventOverlap={false}` and the grid rejects any drag or resize that would land an event on top of another, without you checking in `onDragEvent`. For your own rules, `eventsOverlap` and `overlapsOtherEvents` are exported from `@super-calendar/core`. ```tsx theme={null} ``` ### Haptics on grab `onDragStart` fires the instant an event is picked up for a move or resize, before anything is committed. The library is expo-free, so bring your own haptics: ```tsx theme={null} import * as Haptics from "expo-haptics"; { void Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Medium); }} />; ``` ### Move an event to another week While moving an event, drag it past the left or right edge of the day columns and hold briefly. The view pages to the previous/next period and the event lifts into a floating copy that keeps following your finger, so the drag stays live across the page change and you drop it on any day of the newly revealed week. Both renderers need `onChangeDate` set (they already do for paging); the page only advances on a deliberate dwell at the very edge, so a normal in-view drag never trips it. On native the pager's own swipe is frozen for the moment it pages, so the view advances under your held finger instead of waiting for you to lift. On native, the floating copy's horizontal centre selects the destination day. Its top edge selects the time. This also applies to narrower boxes for overlapping events, so a copy mostly over a day lands in that column even if its left edge crosses the previous column. In-view move, cross-day within the visible columns, and resize all work by gesture as usual on both. On the DOM time grid, only mouse drags trigger edge paging. Touch and pen drags remain inside the visible period. A resting finger cannot repeatedly change the date or detach its captured event through an edge page. ### Rescheduling without dragging Dragging is a gesture, so every renderer offers the same moves and resizes another way. They run through the same commit path as a drag, so `onDragEvent` fires exactly as it would from a gesture (and can still return `false` to reject). `eventOverlap={false}`, `draggable: false`, `startEditable`, and `durationEditable` apply as they do to a drag. On React DOM and Solid, choose **Edit events**, then an event, to open a dialog with **Move 15 minutes later / earlier**, **Extend / Shorten by 15 minutes**, and **Move to next / previous week** (per mode: the page span), stepping by `dragStepMinutes`. It works with a keyboard, a click, or a tap, and never presses or drags the event itself. Rejected edits show a polite status message, customizable with `labels.eventChangeRejected`. Pass `getEventId` to retain the dialog's event through full data refreshes. See [Move and resize actions](/guides/accessibility#move-and-resize-actions-web). On the React Native renderer draggable events also carry **accessibility actions** for VoiceOver / TalkBack users: *move earlier*, *move later*, (when the event owns its end) *extend* / *shorten*, and *move to next / previous week* (per-mode: the page span), each stepping by `dragStepMinutes` or a whole page. The built-in event renderer wires these up automatically; a custom `renderEvent` should spread the `accessibilityActions` and `onAccessibilityAction` it receives onto its pressable to keep the event operable by assistive tech. ## Drag to create Pass `onCreateEvent` to sweep out a new event on empty grid space: **long-press and drag** on native, **click-drag** on web. The handler receives the snapped `start`/`end` on release (a stationary press yields a one-step range). On native it supersedes `onLongPressCell`; on web, dragging empty space creates instead of scrolling (use the wheel to scroll), and **Escape** cancels an in-progress sweep before it commits. ```tsx theme={null} setEvents((prev) => [...prev, { id: makeId(), title: "New event", start, end }]) } /> ``` > [!NOTE] > > A live ghost box previews the range as you sweep. Tap (no drag) on empty space still fires > `onPressCell` with the pressed date+time, so you can support both "tap to create a point" and > "drag to create a range." On the web, the time-grid preview stays inside the visible hours. When a sweep passes the start or end of those hours (00:00 and 24:00 by default, or `minHour` and `maxHour`), the preview stops at that edge. Its border and minimum height stay inside the column, including borders from a `createGhost` class or style. The preview does not change `onCreateEvent`, which still receives the snapped range within the pressed day. ### Show a draft in the preview The preview is empty by default. To show a draft title or the live time range inside it, pass a `renderCreateGhost` component. It receives `start` and `end` as `Date`s: the snapped range `onCreateEvent` would receive if the sweep ended at the pointer's current position. They are ordered, at least one `dragStepMinutes` step long, and clamped to the pressed day, exactly as on release. The component re-renders whenever the range changes, before `onCreateEvent` fires. ```tsx theme={null} import { Calendar, type CreateGhostArgs } from "@super-calendar/dom"; import { format } from "date-fns"; function DraftPreview({ start, end }: CreateGhostArgs) { return (
New event
{`${format(start, "HH:mm")} - ${format(end, "HH:mm")}`}
); } setEvents((prev) => [...prev, { id: makeId(), title: "New event", start, end }]) } renderCreateGhost={DraftPreview} />; ``` On React Native, return `Text` (and views) instead of DOM elements: ```tsx theme={null} import { Calendar, type CreateGhostArgs } from "@super-calendar/native"; import { format } from "date-fns"; import { Text } from "react-native"; function DraftPreview({ start, end }: CreateGhostArgs) { return ( {`New event\n${format(start, "HH:mm")} - ${format(end, "HH:mm")}`} ); } ; ``` In Solid, read the props inside JSX instead of destructuring them, so the text follows the sweep: ```tsx theme={null} import { Calendar, type CreateGhostArgs } from "@super-calendar/solid"; import { format } from "date-fns"; function DraftPreview(props: CreateGhostArgs) { return ( {`New event ${format(props.start, "HH:mm")} - ${format(props.end, "HH:mm")}`} ); } ; ``` The calendar still positions, sizes, and styles the preview (including the `createGhost` slot), and you own only its content. That content is clipped to the preview box, ignores the pointer, and stays out of the tab order and the accessibility tree, like the empty preview. Keep it visual: controls inside it can't be reached. A few rules apply: * `renderCreateGhost` needs `onCreateEvent`. On its own it does not enable creation, and with only `onPressCell` the preview stays empty. Removing `onCreateEvent` cancels an active sweep. * In React, define the component once outside render, as with `renderEvent`. A new inline function on every render remounts the content and drops its state. * `Calendar` forwards it in the time-grid modes (`day`, `3days`, `week`, `custom`). Month and year sweeps don't use it. `ResourceTimeline` accepts the same prop and adds the lane's `resource` to the props, in both orientations. * The range can extend past a narrowed `minHour`/`maxHour` window. On the web the preview box stops at the visible edge, but `start` and `end` keep matching what `onCreateEvent` will receive, which is clamped to the pressed day, not to the visible hours. * In React DOM and Solid, scrolling or zooming during a held sweep updates the preview range even if the pointer does not move again before release. * The content clears when the sweep ends or is cancelled, and each new sweep mounts it fresh. Changing the pressed column to another day cancels the sweep. In React DOM and Solid, **Escape** or losing pointer capture cancels the sweep, and a press without a drag shows the one-step range while held, then fires `onPressCell` instead of creating. On React Native, a stationary hold creates that one-step range. A cancelled native gesture clears the preview without calling `onCreateEvent`. * On React Native, the preview geometry stays on the UI thread. Pointer and zoom updates cross to JavaScript only when the snapped range changes. ## On the month grid The same two handlers work in `month` mode on both renderers. Nothing extra to enable: pass `onCreateEvent`, `onDragEvent`, or both. ### Drag to create a day span Press an empty day and drag across others to sketch an **all-day** span, then release. `start` is midnight of the first day and `end` is midnight after the last (exclusive). On native you **long-press** first, so a tap and a page swipe are never hijacked, and a stationary hold creates that single day; on web a plain click without dragging creates nothing and still fires `onPressDay`. ```tsx theme={null} setEvents((prev) => [...prev, { id: makeId(), title: "New", start, end, allDay: true }]) } /> ``` `onSelectDrag` reports the **same sweep** as it happens, with the ordered inclusive `[start, end]` days, so a selection highlight can follow the drag rather than appearing only on release. Set it, `onCreateEvent`, or both; either enables the gesture. See [Date selection](/guides/selection) for wiring it to `useDateRange`. ### Drag to reschedule Pick an event bar up and drop it on another day. Both ends shift by the same number of calendar days, so the **time of day and the duration are preserved** (a multi-day event keeps its length). Grab it with a **long-press** on native and a **press-drag** on web. The carried bar fades and the target day is tinted while you drag. ```tsx theme={null} setEvents((prev) => prev.map((e) => (e.id === event.id ? { ...e, start, end } : e))) } /> ``` Everything above applies here too: `draggable: false` and `startEditable: false` lock an event, `eventStartEditable={false}` locks the whole grid, returning `false` rejects a drop, and `eventOverlap={false}` rejects one that would land on top of another event. `onDragStart` fires on grab, for haptics. There is no resize on the month grid, so `durationEditable` has no effect there. ### Styling the drag states Both states are tinted with the theme's `rangeBackground` token by default (see [Theming](/guides/theming)), and the bar being carried fades. On the dom renderer each day in a create sweep also carries `data-creating` and the day an event is about to land on carries `data-drop`, so you can restyle either (see [Styling](/guides/styling)); give the `day` slot a class to take the tint over entirely. ## On the year grid The twelve mini months take the same sweep: `onSelectDrag` reports the ordered inclusive `[start, end]` days as you drag, and `onCreateEvent` reports the all-day range once on release. Hold a day and drag on a device, press and drag on the web. Days being swept carry `data-creating` on the dom renderer. ```tsx theme={null} setEvents((prev) => [...prev, { id: makeId(), title: "Leave", start, end, allDay: true }]) } /> ``` On a device a sweep stays inside the mini month it started in; on the web it can carry on across months. The year view summarises events as dots rather than bars, so it has nothing to pick up: `onDragEvent` applies to `month` mode, not `year`. ## Tuning the snap `dragStepMinutes` (default 15) controls how move, resize, and create snap on the week/day grid. The month and year grids always snap to whole days. # Custom events Source: https://super-calendar.afonsojramos.me/guides/events Type your events and render them your way. ## The event type Events are plain objects. The only required fields are `start`, `end`, and `title`; everything else is yours. `CalendarEvent` is generic, so you can attach your own fields and read them back in callbacks and renderers. ```tsx theme={null} import type { CalendarEvent } from "@super-calendar/native"; type Meta = { id: string; calendarId: string; color: string }; const events: CalendarEvent[] = [ { title: "Standup", start: new Date(2026, 5, 23, 9, 0), end: new Date(2026, 5, 23, 9, 30), id: "1", calendarId: "work", color: "#1F6FEB", }, ]; ``` * `allDay` lays the event out in the all-day lane above the grid instead of in the columns. It's also inferred for midnight-to-midnight spans. Pass `showAllDayEventCell={false}` to hide the lane entirely (its events won't show). In the `schedule` view (which has no lane) an all-day event reads "All day" instead of a time range; override the wording with `allDayLabel` (e.g. for a different language). * `disabled` opts an event out of drag interactions. * `draggable`, `startEditable`, and `durationEditable` control per-event drag and resize (see the [drag guide](/guides/dragging)). * `dragHandleColor` overrides the resize grip colour for an event in the native time grid and resource timeline. It defaults to `theme.colors.eventText`. * Multi-day events draw as one continuous bar across the days they span in the month view, and as a per-day clipped segment on the week/day time grid. ## Keep event data stable Keep the `events` array and its event objects stable while only UI state changes, such as a drag indicator set by `onDragStart`. Pass stored data as `events={events}`. If you filter or map it, memoize the result with React's `useMemo` or Solid's `createMemo`, using the source data as a dependency. Update event data immutably when it changes. With `Calendar` recurrence or `timeZone`, a new array rebuilds the displayed occurrences, even if the array contains the same source objects. In the multi-week web grid, replacing the held event cancels the move. Keep unrelated state updates from rebuilding `events`, including inline copies such as `events={[...events]}`. A data refresh can still cancel an active move safely. The native `keyExtractor` controls rendering keys; it does not reconnect a held gesture to a replacement event. ## Render your own event For Solid, use the [custom event example](/guides/solid#render-custom-events). For React DOM, see the [web renderer guide](/guides/dom). Both web `Calendar` components use separate renderers for timed, month, and schedule events. On React Native, pass `renderEvent`, a component that receives `RenderEventArgs`. It's used in every mode and for every event shape (timed, all-day, multi-day), so you only write it once. ```tsx theme={null} import type { RenderEventArgs } from "@super-calendar/native"; import { Pressable, Text } from "react-native"; function MyEvent({ event, onPress }: RenderEventArgs) { return ( {event.title} ); } ; ``` > [!TIP] > > Wrapping events in a portaling overlay (a context menu, popover) on the web? Portal it into your > app's React root, not `document.body` — see the [Web guide](/guides/web#portaling-overlays). On the day/week grid a timed event's box is sized to its duration and given to your renderer as `boxHeight`, so it tracks the grid's hour scale as the grid zooms or resizes. Fit your content to `boxHeight`: the built-in renderer clamps its own content, and a custom renderer should adapt (show less, or scroll) rather than assume a fixed size, since content taller than the slot is clipped. `boxHeight` never drops below the grid's `minEventHeight` (default 32 on native, 14 on the dom renderer); set it to `0` if your renderer should get the exact duration height. The box is inset from its slot by `eventGap` (see [Event boxes](/guides/time-grid#event-boxes)). ## Lighter touches If you only want to tweak the built-in event box, you don't need a full `renderEvent`: * `eventCellStyle` — a style (or a function of the event) merged onto the built-in box. * `keyExtractor` — a stable key per event; defaults to start-time + index. * `showTime` shows the time range under the title (default true). The title comes first: on the day/week grid it fills the box with as many whole lines as fit (never a half-cut line), and the time only appears once a full line is free beneath it. * `ellipsizeTitle` ends a single-line title (the all-day lane, month cells) with a trailing ellipsis when it overflows, instead of a hard clip (default false). ## Screen-reader labels Each event announces a built-in label: its title plus the time range (or "all day"), which the grid otherwise only shows visually. Override it per event with `eventAccessibilityLabel`. It receives the event and a `{ mode, isAllDay, ampm }` context, and its return value replaces the default label across every view. ```tsx theme={null} isAllDay ? `${event.title}, all day` : `${event.title}, from ${format(event.start, "h:mm a")} to ${format(event.end, "h:mm a")}` } /> ``` The same prop is on the standalone `MonthView`, `MonthList`, and `TimeGrid`, so a custom renderer and its label stay in sync. ## Background events Set `display: "background"` to paint an event's time range as a shaded, non-interactive band behind the grid instead of an event box — blocked time, maintenance windows, public holidays: ```tsx theme={null} const events: CalendarEvent[] = [ { title: "Maintenance", start: at(9), end: at(12), display: "background" }, { title: "Standup", start: at(9), end: at(10) }, // renders normally, on top ]; ``` Background events shade the time grid and the resource timeline's lanes (an all-day or multi-day one covers each day's full window). They take no overlap column, render no chip in the month grid or agenda, and produce no year-view dot. Restyle the band with the `backgroundEvent` slot or the theme's `backgroundEvent` colour token. To draw a band yourself, or make it pressable, pass a component as `renderBackgroundEvent` to `Calendar` or `TimeGrid` on either renderer (the resource timeline keeps the shade). It is rendered like `renderEvent`, so it may use hooks, and receives the `event`, the `mode`, the band's `boxHeight`, the `ampm` flag, `continuesBefore` / `continuesAfter` for a multi-day event, and `onPress`, which fires `onPressEvent`; React Native adds `onLongPress` and makes `boxHeight` a live shared value that follows a pinch. The themed tint is dropped, the band lets touches or pointer events through to what you render, and it is no longer hidden from assistive tech. On the web the band itself takes no focus, so render a focusable control such as a button for keyboard users. Cell presses and drag-to-create are unreachable underneath such a band. Define the component outside your render so it keeps its identity (on the web the args type is `DomRenderEventArgs` from `@super-calendar/dom`): ```tsx theme={null} import { Pressable, Text } from "react-native"; import { Calendar, type RenderEventArgs } from "@super-calendar/native"; function BlockedBand({ event, onPress }: RenderEventArgs) { return ( {event.title} ); } console.log(event.title)} />; ``` ## Loading events from a feed `useEventSource` (from `@super-calendar/core`) owns the fetching for you: point it at a JSON feed, an iCalendar feed (`.ics` URLs are parsed automatically), or your own async function, and hand the result to any view. Set `refetchIntervalMs` for a live feed; `refetch` reloads on demand, and a failed refetch keeps the previous events while reporting `error`. ```tsx theme={null} import { useEventSource } from "@super-calendar/core"; const { events, loading, error, refetch } = useEventSource("https://example.com/rooms.ics", { refetchIntervalMs: 5 * 60_000, }); ; ``` JSON feeds default to items with ISO `start`/`end` strings; pass `map` to reshape anything else (rename fields, attach a `resourceId`, filter). The default mapper validates calendar fields and revives recurrence `until`, `exdates`, and `rdates`. Invalid data rejects the batch and sets `error`, keeping the previous events. A custom `map` receives an array of unknown items and owns their validation and conversion. Extra event fields are preserved. Polling requires a finite `refetchIntervalMs` greater than zero and no larger than `2147483647` (the timer limit, about 24.8 days). Other values disable it. Unmounting stops polling and aborts pending URL requests. Retained `refetch` callbacks do nothing after unmount. One nuance for function sources: swapping the function itself doesn't trigger a refetch (inline functions change identity every render, which would loop). The next interval tick or a manual `refetch()` always calls the latest function, so change what the function reads, or call `refetch()` after swapping it. In Solid, use [`createEventSource`](/guides/solid#load-an-event-feed). Its source and options are accessors, and changes to either trigger a reload, including a new async function. For one batch without a reactive owner, import `loadEventSource` from `@super-calendar/core/vanilla` or `@super-calendar/core`: ```ts theme={null} import { loadEventSource } from "@super-calendar/core/vanilla"; const controller = new AbortController(); const events = await loadEventSource({ source: "/events.json", signal: controller.signal }); ``` The loader accepts `source`, `format`, `map`, and an optional `signal`. It does not poll or retain state. HTTP failures, malformed JSON feeds, and cancellation reject its promise. The abort signal applies to URL requests; custom async functions manage their own cancellation. # Headless core Source: https://super-calendar.afonsojramos.me/guides/headless Build a fully custom calendar from @super-calendar/core's pure logic. `@super-calendar/core` is the shared engine the renderers are built on: date math, the selection model, event layout, recurrence, time-zone conversion, and the neutral theme tokens. Reach for it directly only when you want entirely custom UI. Most apps use the [native](/quickstart) or [react-dom](/guides/dom) or [Solid](/guides/solid) components, which already wrap all of this. ```bash theme={null} npm install @super-calendar/core date-fns ``` `react` is an optional peer dependency. The root entry imports React for its hooks. Import `@super-calendar/core/vanilla` when you need pure functions without React, including on a server or in a Solid app: ```ts theme={null} import { buildMonthGrid, layoutDayEvents, nextDateRange } from "@super-calendar/core/vanilla"; ``` The vanilla entry exports the pure core types and helpers, excluding React hooks and providers. Existing `@super-calendar/core` imports continue to work. ## Month grid When you want your own day-cell markup but not the date maths, `useMonthGrid` gives you the grid as data: the weeks, the weekday headers, and per-day state (today, selected, in-range, disabled, current-month). You render whatever you like. ```tsx theme={null} import { View, Text, Pressable } from "react-native"; import { useMonthGrid } from "@super-calendar/core"; function MyMonth({ month, range }: { month: Date; range?: DateRange }) { const { weeks, weekdays } = useMonthGrid(month, { weekStartsOn: 1, selectedRange: range, }); return ( {weekdays.map((w) => ( {w.label} ))} {weeks.map((week) => ( {week.days.map((day) => ( {day.label} ))} ))} ); } ``` ### Per-day state Each `day` in `weeks[].days` carries: | Field | Notes | | - | - | | `date` | The `Date` for the cell. | | `id` | Stable `yyyy-MM-dd` string (handy as a React key). | | `label` | Day of month, e.g. `"1"`. | | `isCurrentMonth` | False for leading/trailing adjacent-month days. | | `isToday` | Matches the real today. | | `isWeekend` | Saturday or Sunday. | | `isDisabled` | Fails `minDate`/`maxDate`/`isDateDisabled`. | | `isSelected` | A `selectedDates` day or a range endpoint. | | `isRangeStart` / `isRangeEnd` | The range's two endpoints. | | `isInRange` | Inside a complete range (endpoints included). | `useMonthGrid(month, options)` accepts `weekStartsOn`, `showSixWeeks`, `isRTL`, `locale`, `selectedDates`, `selectedRange`, and the `minDate` / `maxDate` / `isDateDisabled` constraints. > [!TIP] > > Need the grid outside React (tests, server, exports)? Call the pure `buildMonthGrid(month, > options)`; `useMonthGrid` is just a memoized wrapper around it. `buildMonthWeeks(month, > weekStartsOn)` returns the raw `Date[][]`. `layoutMonthWeek(days, events)` lays one week row's events out as spanning bars: each event becomes a single segment carrying the `startCol` / `endCol` it covers, a `lane` for stacking overlapping events, and `continuesBefore` / `continuesAfter` flags for bars that run past the row's edges. It's the same layout the built-in month grid uses, so a custom month cell can draw identical multi-day bars. ## Laying out timed events `layoutDayEvents(events, day)` resolves overlaps into side-by-side columns for a day/week grid — the same math the `TimeGrid` uses, with no rendering opinion. Each `PositionedEvent` gives you placement: ```tsx theme={null} import { layoutDayEvents } from "@super-calendar/core"; for (const pe of layoutDayEvents(events, day)) { // pe.event the original event // pe.startHours, pe.durationHours vertical position (clock hours) // pe.column / pe.columns left = (column / columns) * 100%, width = 100% / columns // pe.continuesBefore / pe.continuesAfter multi-day clipping flags } ``` `startHours` is the clock time, not the time elapsed since midnight, so on a daylight saving change day an event still lines up with its hour label. To place your own marks the same way, use `wallClockHours(date, dayStart, nextDayStart)`, which reads the clock and clamps to the day (the closing midnight reads 24). `clockHoursBetween(from, to)` gives the rows a span covers: 01:30 to 03:30 is 2 even on a spring-forward day, when only 1 hour passes. To bucket events by calendar day (for a month or agenda), use `groupEventsByDay(events)` — a `Map` keyed by `startOfDay(date).toISOString()` that indexes multi-day events under every day they span. `eventDayKeys(event)` returns those keys for a single event. ## More in core Every helper below is pure (safe in tests, on a server, or in a worker). See the TypeScript types for exact signatures. * **Drag math** — `cellRangeFromDrag` (a sweep to start/end), `resolveDraggedBounds` (a move/resize to snapped bounds), `clampMoveStartMinutes` (holds a moved start inside the visible hour window), `snapDeltaMinutes`, `shiftMinutes`, `movedClockSpan` (where a move previews on a daylight saving change day). * **Event display** — `eventTimeLabel`, `eventAccessibilityLabel`, `titleNumberOfLines` / `titleEllipsizeMode`, `isTimeVisibleAtHeight`, `formatHour` (the shared time-grid hour-axis label both renderers default to). * **Labels** — `resolveCalendarLabels` fills a partial `labels` object with the English defaults; `dayAccessibilityLabel` builds a day label from a formatted date and its state words. Pass the resolved labels to `eventAccessibilityLabel` to localize a custom renderer's event label the same way. * **Month overflow** — `monthEventCapacity` + `monthVisibleCount` decide how many chips fit before a "+N more" row. * **Business hours** — `closedHourBands(day, businessHours, minHour?, maxHour?)` returns the hour spans to shade. * **Presentation** — `rangeBandKind`, `bandRounding`, `dayBadgeKind` map a day's selection state to pill/badge intent (exactly what both renderers consume). * **Selection** — the `useDateRange` hook, plus pure `nextDateRange`, `daySelectionState`, `isDateSelectable`, `isRangeEndpoint`, `isWithinDateRange`. * **Dates** — `getViewDays`, `getWeekDays`, `getIsToday`, `isWeekend`, `isSameCalendarDay`, `minutesIntoDay`, `isAllDayEvent`. * **Theme tokens** — `lightColors` / `darkColors` (the neutral `CalendarColors` palette) to build a theme from scratch. Recurrence (`expandRecurringEvents`) and time zones (`eventsInTimeZone`, `toZonedTime`) are pure core helpers too; see the [Recurring events](/guides/recurring-events) and [Time zones](/guides/time-zones) guides. # iCalendar (.ics) import & export Source: https://super-calendar.afonsojramos.me/guides/ical Read and write RFC 5545 .ics files so events interoperate with Google, Apple, and Outlook. `@super-calendar/core` ships `parseICalendar` and `toICalendar` to convert between `.ics` text and the library's `CalendarEvent` shape — so a calendar built with super-calendar can import feeds from, and export to, Google Calendar, Apple Calendar, Outlook, and anything else that speaks iCal. ```ts theme={null} import { parseICalendar, toICalendar } from "@super-calendar/core"; // also re-exported from "@super-calendar/dom" and "@super-calendar/native" ``` ## Import `parseICalendar(text)` returns an array of events you can pass straight to a ``: ```ts theme={null} const res = await fetch("/calendar.ics"); const events = parseICalendar(await res.text()); // -> [{ uid, title, start, end, allDay?, description?, location?, recurrence? }] ``` Each event carries the standard fields it round-trips: `uid`, `description`, `location`, plus `allDay` (from `VALUE=DATE`) and a `recurrence` parsed from `RRULE`. Recurring events are returned as a single event with a rule — expand them for a date range with [`expandRecurringEvents`](/guides/recurring-events): ```ts theme={null} import { expandRecurringEvents, parseICalendar } from "@super-calendar/core"; const occurrences = expandRecurringEvents(parseICalendar(ics), rangeStart, rangeEnd); ``` ## Export `toICalendar(events)` produces a complete `VCALENDAR` string. Timed events are written in UTC; set `allDay: true` for `VALUE=DATE` events; a `recurrence` becomes an `RRULE`. ```ts theme={null} const ics = toICalendar(events); // Offer it as a download in the browser: const url = URL.createObjectURL(new Blob([ics], { type: "text/calendar" })); ``` Pass `{ prodId, now }` to set the calendar's `PRODID` and the `DTSTAMP` written on each event. A stable `UID` is derived from the event when you don't supply one, so re-exports stay diff-friendly. ## What's covered A pragmatic subset of RFC 5545, aimed at real-world event interchange: * **`VEVENT`** with `SUMMARY`, `DESCRIPTION`, `LOCATION`, `UID`, `DTSTART`, and either `DTEND` or `DURATION` (e.g. `PT1H30M`, `P1D`). * **All-day** events via `VALUE=DATE` (a missing end becomes a one-day span). * **Dates** in UTC (`...Z`), a named IANA zone (`TZID=Europe/London`, resolved to the correct instant), floating local, or date-only; line folding and text escaping per the spec. * **`RRULE`** round-tripped to a [`RecurrenceRule`](/guides/recurring-events) (`FREQ`, `INTERVAL`, `COUNT`, `UNTIL`, weekly `BYDAY`, and ordinal `BYDAY` like `3MO`/`-1FR` → `nthWeekday`), plus **`EXDATE`** exception days (`recurrence.exdates`, honoured by `expandRecurringEvents`). Not (yet) handled: `VTODO` / `VJOURNAL`, `VALARM`, attendees, attachments, and embedded `VTIMEZONE` definitions (a `TZID` must be a valid IANA name for the runtime's `Intl`). Contributions welcome. # Month list Source: https://super-calendar.afonsojramos.me/guides/month-list A vertically-scrolling, continuous list of months (the date picker). `MonthList` renders months stacked vertically in one continuous, virtualized scroll: a month-title separator followed by each month's grid, under a single fixed weekday header. Each month shows **only its own days** (no dimmed adjacent-month fill), and sizes to its own row count. It's the home for date picking. It takes the same selection props as [`MonthView`](/reference/api) and renders a range band that flows continuously across month boundaries, which the horizontally-paged month view can't do. An events-free picker needs nothing but `date` and the selection wiring: > [!TIP] > > For a picker-only app, import from the `@super-calendar/native/picker` entry point. It excludes > the timetable views and Reanimated, so the bundle stays small and you can skip the > `react-native-reanimated` / `react-native-worklets` peers. ```tsx theme={null} import { MonthList, useDateRange } from "@super-calendar/native"; function RangePicker() { const [date, setDate] = useState(new Date()); const { range, onPressDate, selectRange } = useDateRange({ minDate: new Date() }); return ( ); } ``` Tap two days to set the range ends, or long-press and drag to sweep one out (the list auto-scrolls at the edges so a range can span months). Pass `events` (plus an optional `renderEvent`) to show events in the grids too; it reuses `MonthView`, so events, selection, and disabled days behave as in the month view. The React DOM and Solid versions update mounted months when callbacks, date constraints, themes, or slots change. You do not need to replace `date` or `events` to apply those updates. ## Props | Prop | Type | Notes | | - | - | - | | `date` | `Date` | The month scrolled to on mount. | | `weekStartsOn` | `0–6` | First day of the week. | | `events` | `CalendarEvent[]` | Optional; omit for an events-free picker. | | `weekRowHeight` | `number` | Height of each week row (px). Default 56. | | `monthHeaderHeight` | `number` | Title-row height (px). Default 44. A custom header must fit it. | | `renderEvent` | `RenderEvent` | Optional; defaults to `DefaultEvent`. | | `keyExtractor` | `(event, index) => string` | Optional; defaults to start-time + index. | | `selectedDates` | `Date[]` | Selected days (see [Selection](/guides/selection)). | | `selectedRange` | `DateRange` | Selected span. | | `minDate` / `maxDate` | `Date` | Bound the selectable range. | | `isDateDisabled` | `(date) => boolean` | Disable specific days. | | `onSelectDrag` | `(start, end) => void` | Drag-to-select; pair with `useDateRange().selectRange`. | | `showAdjacentMonths` | `boolean` | Show dimmed adjacent-month days. Default `false`. | | `highlightWeekends` | `boolean` | Tint weekend day cells. Default `true`. | | `onPressDay` | `(date) => void` | Tap a day cell. | | `onChangeVisibleMonth` | `(month) => void` | Fires with the topmost month once it's \~60% visible. | | `renderMonthHeader` | `(month) => ReactNode` | Replace the default `LLLL yyyy` title. | # Month view Source: https://super-calendar.afonsojramos.me/guides/month-view The month grid, event chip fitting, overflow, and month paging. > [!NOTE] > > Examples use the React Native `Calendar`; most props are shared with the dom renderer, and the > [dom vs native comparison](/reference/renderers) lists what differs per renderer. `mode="month"` renders the classic month grid: a swipeable pager of 4–6 week rows. A single-day event shows as a chip in its day cell; an event that covers several days draws as one continuous bar spanning the columns it touches, so a trip or holiday reads as a single block instead of a chip repeated on each day. A bar that runs past a week's edge is squared off and continues on the next row. ```tsx theme={null} { setDate(day); setMode("day"); }} /> ``` For a fixed count of consecutive full weeks, use `mode="multiweek"` or `MultiWeekView`. It shares the event bars, overflow, selection, drag interactions, and month styling described here. `numberOfWeeks` defaults to two, and `showAdjacentMonths`/`showSixWeeks` do not affect it. See [multi-week grids](/guides/views#multi-week-grids). ## Chip dimensions Set `chipHeight` and `chipGap` on `Calendar`, `MonthView`, or `MonthList` to size month lanes, spanning bars, and overflow rows. Native `MonthPager` forwards them too. Custom event renderers must fit inside the configured height. You can change either dimension after mounting, including in cached list and pager months. DOM defaults remain 18 px for height and 2 px for gaps. Native keeps its theme-derived height and 2 px gaps when you omit the options. Choose a smaller `maxVisibleEventCount` if larger chips cannot fit within your calendar height. ## Event chips and overflow Each week row stacks its events into lanes (a multi-day bar keeps its lane across the days it spans) and shows as many lanes as the cell height allows, collapsing the rest of a day's events into a `+N more` label. ```tsx theme={null} // auto-fit (default) // fixed cap ``` * `maxVisibleEventCount` — a fixed cap on **lanes per week row** instead of auto-fit. Because a multi-day bar occupies a lane across the whole week, a long bar can push a lightly-booked day's own events into `+N more`. Recommended when you pass a custom `renderEvent`, since auto-fit assumes the built-in chip height. * `onPressMore` — tap the overflow label; receives the hidden events and the day. Without it, the built-in popover opens instead, listing the day's events (style it via the `morePopover` slot). * `moreLabel` — customize the overflow text (e.g. `"+{moreCount}"`). * `sortedMonthView` — sort each day's chips by start time (default on); all-day events lead the day. ## Grid shape * `showTitle` — the built-in "July 2026" label above the grid (default on). Set `showTitle={false}` when your own header already shows the month and year, so the label isn't duplicated. * `showSixWeeks` — always render six week rows for a fixed-height grid. * `showAdjacentMonths` — show (dimmed) days from the neighbouring months (default on). * `weekStartsOn` — 0 = Sunday, 1 = Monday, and so on. * `weekdayFormat` — header label width: `narrow` ("M"), `short` ("Mon"), or `long` ("Monday"). * `hiddenDays` — weekdays (0=Sunday…6=Saturday) dropped from the grid and its header, e.g. `[0, 6]` for weekends off. Also applies to the year view. * `highlightWeekends` — tint Saturday and Sunday cells with the weekend background (default on). Pass `highlightWeekends={false}` to treat them like any other day, or recolour the tint via the `weekendBackground` [theme](/guides/theming) token. ## Taps and custom cells `onPressDay` / `onLongPressDay` fire for the cell, `onPressEvent` / `onLongPressEvent` for a chip. `onPressCell` fires for the cell too, with the day at midnight, so the handler you already use to create events on the week/day grid works unchanged in month mode: ```tsx theme={null} openNewAppointment(day)} // midnight of the tapped day onPressDay={(day) => { setDate(day); setMode("day"); }} /> ``` Replace parts of the cell with `renderCustomDateForMonth` (the date badge) or a custom `renderEvent` (see [Custom events](/guides/events)); restyle everything else through the [theme](/guides/theming) or per-slot [classes](/guides/styling). ## Dragging Month cells and chips are draggable too: pass `onCreateEvent` to sweep out an all-day span across days, and `onDragEvent` to drop an event on another day (keeping its time of day and duration). See [Drag & create](/guides/dragging#on-the-month-grid). ## Selecting, creating, and moving by drag The month grid is drag-driven too, in whole days. **Hold an empty day and drag** across others (press and drag on the web) to sweep a span: `onSelectDrag` reports it live as the ordered `[start, end]` days, `onCreateEvent` reports it once on release as an all-day range. **Hold an event chip** and drop it on another day and `onDragEvent` fires with the event shifted by whole days, keeping its time of day and duration. `selectedDates` / `selectedRange` (with `minDate`, `maxDate`, `isDateDisabled`) draw the selection. ```tsx theme={null} ``` See [Drag & create](/guides/dragging) and [Date selection](/guides/selection) for the details. Looking for a vertically scrolling list of months instead of a pager, or an events-free month grid for picking dates? That's [MonthList](/guides/month-list). # Recurring events Source: https://super-calendar.afonsojramos.me/guides/recurring-events Expand recurrence rules into concrete occurrences. Give an event a `recurrence` rule and `Calendar` expands it into concrete occurrences automatically: over the visible range in the `month`, `week`, `day`, `3days`, and `custom` modes, and over a rolling three-month window in `schedule` (the agenda has no bounded viewport of its own). Non-recurring events pass through untouched, so you can mix both freely. ```tsx theme={null} import { Calendar } from "@super-calendar/native"; const events = [ { title: "Standup", start, end, recurrence: { freq: "weekly", weekdays: [1, 2, 3, 4, 5] } }, ]; ; ``` When you want the occurrences yourself (to save, export to iCal, or list them over a window of your own), expand them with `expandRecurringEvents` and pass the result as `events`: ```tsx theme={null} import { Calendar, expandRecurringEvents } from "@super-calendar/native"; const events = [ // Every weekday standup, 20 occurrences: { title: "Standup", start, end, recurrence: { freq: "weekly", weekdays: [1, 2, 3, 4, 5], count: 20 }, }, ]; const visible = expandRecurringEvents(events, rangeStart, rangeEnd); ; ``` Rules support: * `freq` — `"daily"`, `"weekly"`, `"monthly"`, or `"yearly"`. * `interval` — every N periods (e.g. every 2 weeks). * `count` — stop after N occurrences. * `until` — stop on or before a date. * `weekdays` — which days, for `weekly` rules (0 = Sunday). * `nthWeekday` — for `monthly`/`yearly`, repeat on the Nth weekday instead of the day-of-month, e.g. `{ week: 3, weekday: 1 }` (the 3rd Monday) or `{ week: -1, weekday: 5 }` (the last Friday). * `monthDays` — for `monthly`, the day(s) of the month to repeat on, e.g. `[1, 15]` (the 1st and 15th) or `[-1]` (the last day; negatives count from the month's end). Days a month lacks (the 31st in February) are skipped. * `months` — for `yearly`, the month(s) to repeat in (1 = January … 12 = December), keeping the start date's day-of-month, e.g. `[3, 9]` (every March and September). * `exdates` — dates to skip (exceptions). A date at local midnight skips every occurrence on that calendar day; a date with a time skips only the occurrence starting at that exact instant, so two same-day occurrences can be cancelled independently. * `rdates` — extra one-off dates added to the set, even ones the rule wouldn't produce. Each occurrence keeps the original duration and fields; non-recurring events pass through unchanged. These rules map to and from iCal `RRULE`/`BYMONTHDAY`/`BYMONTH`/`EXDATE`/`RDATE` — see [iCalendar](/guides/ical). > [!TIP] > > Compute the range from the visible window. `onChangeDateRange` gives you the `[start, end]` of > what's on screen each time the user pages — a good trigger to re-expand (and to fetch from a > server). Expansion fast-forwards to the range you ask for, so a long-lived rule (a daily event started years ago) stays cheap to query far in the future. A single rule emits at most 5000 occurrences within the range; pass a `count`/`until`, or query a tighter window, if you need more. Expansion stops if the next date exceeds JavaScript's representable date range and omits occurrences whose end would overflow that range. # Resource timeline Source: https://super-calendar.afonsojramos.me/guides/resource-timeline A one-day timeline with a lane per resource (room, person, machine), horizontal or vertical. > [!NOTE] > > Available on **React DOM, Solid, and React Native**, including drag-to-move and edge-resize via > `onDragEvent`. The web renderers add per-slot class styling; the React Native renderer > (`@super-calendar/native`) styles via `theme.containers`. Import from the package you're using. The examples below use React. See the [Solid resource example](/guides/solid#schedule-resources) for controlled events with signals. `ResourceTimeline` lays a single day out horizontally: each **resource** is a row, the x-axis is the day's hours, and every event sits in its resource's row at its start time. It's the classic scheduling board — rooms, people, or machines down the side, time across the top — and the MIT answer to the "resource timeline" views other libraries gate behind a paid tier. ```tsx theme={null} import { type CalendarEvent, ResourceTimeline } from "@super-calendar/dom"; const resources = [ { id: "room-a", title: "Room A" }, { id: "room-b", title: "Room B" }, ]; const events: CalendarEvent<{ resourceId: string }>[] = [ { resourceId: "room-a", title: "Standup", start: new Date(2026, 5, 26, 9), end: new Date(2026, 5, 26, 10), }, { resourceId: "room-b", title: "Review", start: new Date(2026, 5, 26, 11), end: new Date(2026, 5, 26, 12), }, ]; ; ``` ## How events map to rows Each event is placed in the row whose `id` matches its resource. By default that's read from `event.resourceId`; pass a `resourceId` accessor for a different shape: ```tsx theme={null} event.room} /> ``` Overlapping events **in the same row** stack into sub-lanes (via the shared `layoutDayEvents`), so nothing is hidden behind anything else. ## Vertical orientation On a narrow screen the horizontal axis has to scroll sideways, which reads poorly. Pass `orientation="vertical"` to flip the layout into the time grid's shape: the hour axis runs down the left, each resource becomes a **column**, and the columns flex to share the available width, so a phone shows the whole board at once. ```tsx theme={null} ``` A common pattern is switching on the viewport, like the example app does: ```tsx theme={null} orientation={width < 600 ? "vertical" : "horizontal"} ``` Everything else carries over: overlapping events share their column as side-by-side sub-lanes, drag-to-move follows the vertical axis, and resize moves to the bottom edge. On React Native the resource headers stay fixed while the hours scroll, so give the timeline a bounded height (a flexed or fixed-height parent); on the web the track scrolls inside the component when you constrain its height. `hourHeight` (default 48) sets the pixels per hour; `hourWidth`, `rowHeight`, and `labelWidth` apply to the horizontal orientation only. Custom renderers get `height` (the bar's pixel height) in their `ResourceEventArgs`; `width` is 0 in this orientation because the columns flex. ## Paging resources Columns flex to share the width, so past a handful of resources they get too narrow, especially at phone widths. `resourcesPerPage` caps how many lanes show at once; `resourcePage` (0-based, clamped to the last page) picks which ones. It's controlled, like `date`: wire your own prev/next buttons to a state value. ```tsx theme={null} const [page, setPage] = useState(0); const pages = Math.ceil(resources.length / 3); ; // Your controls:

{feed.error()?.message}

); } ``` `events()`, `loading()`, and `error()` are accessors. The previous events remain visible during a refresh or an error. A source or options change cancels the previous URL request. Disposal stops polling and cancels pending requests; later `refetch()` calls do nothing. Async function sources cannot be aborted, but their stale results are ignored. Fetching starts on the client, including after hydration; server rendering does not fetch. Use `createEventSource(() => loadEvents)` for your own async function. URL feeds support JSON and iCalendar through the shared [event-source options](/guides/events#loading-events-from-a-feed). The example's **feed** view demonstrates loading and manual refresh. ## Customize the appearance Pass `theme={darkSolidTheme}` for the built-in dark theme, or pass a partial `SolidCalendarTheme`. `mergeSolidTheme` fills omitted tokens with the defaults. Use `className` and `style` on the root, or `classNames` and `styles` for named slots. Slot classes replace themed styles and preserve layout, matching the [web styling contract](/guides/styling). Numeric lengths use pixels. No stylesheet import is needed. ## Render on a server The package's `solid` export lets the Vite plugin compile the library with your app. Use `solid({ ssr: true })` for hydration. Precompiled hydratable browser and server entries are also available through the `browser` and default export conditions. Server rendering does not access the DOM or start timers. Keep the initial dates, events, locale, and time zone equal on server and client. Pass a fixed `now` to make the current-time indicator deterministic. Construct anchor dates in the same local zone on both sides, as described in [time zones](/guides/time-zones#anchor-dates-are-local). The repository's `examples/solid` app includes `/` and `/ssr` routes. Start it with `pnpm --filter @super-calendar/example-solid dev` after `pnpm build`. ## Troubleshoot an integration ### JSX compilation or missing exports Check that `solid-js` and `@solidjs/web` both resolve to `2.0.0-rc.20`. Use `@solidjs/vite-plugin@3.0.0-next.55`, `jsx: "preserve"`, and `jsxImportSource: "@solidjs/web"`. Remove React JSX transforms from the Solid app. Import calendar components from `@super-calendar/solid`; use `@super-calendar/core/vanilla` for shared logic without React. ### Changes do not appear Read accessors in JSX, such as `events={events()}`. Reading `events()` once in the component body captures a snapshot. Keep reactive props as `props.event` inside custom renderers instead of destructuring them. Update event arrays with a signal setter, and replace the edited event object. For helpers such as `createDateRange` and `createEventSource`, pass accessors for changing options. ### Hydration reports mismatches Enable `solid({ ssr: true })`. Insert `generateHydrationScript()` from `@solidjs/web` in the server document before the client entry, and use `hydrate` for the container that already holds server-rendered HTML. Use `render` for an empty client-only container. The repository example shows both paths. Compare the initial date, events, locale, time zone, and `now` on both sides. JSON serializes dates as strings, so restore each date field before passing events to the calendar. Keep browser-only values out of the initial server render. # Styling with Tailwind & CSS Source: https://super-calendar.afonsojramos.me/guides/styling Restyle any part of the calendar with per-slot classes and inline styles, on the web and on React Native. > [!NOTE] > > Both renderers support per-slot `classNames` / `styles`. On the web they work with any CSS setup; > on React Native the classes need a Tailwind runtime such as [uniwind](https://docs.uniwind.dev) or > NativeWind (see [React Native](#react-native-uniwind--nativewind) below). For colours, typography, > and metrics in one place, see [Theming](/guides/theming). The components render with inline styles driven by the [theme](/guides/theming), so a zero-config `` looks complete with no stylesheet. But inline styles beat external CSS, which would leave a Tailwind class powerless to override them. To close that gap, every styleable part is a named **slot** you can target with a class, an inline style, or a `data-*` state variant. ## Per-slot classes Pass `classNames` to hand a slot over to your own CSS or Tailwind: ```tsx theme={null} import { MonthView } from "@super-calendar/dom"; ; ``` The contract, per slot: * **Structural styles always apply** — the layout the component needs to hold together (grid templates, flex, positioning). Your class is added on top; you never have to re-implement the grid. * **Themed styles drop when you pass a class** — colour, typography, spacing, and borders step aside so your class wins instead of losing to an inline style. So `classNames={{ title: "text-center" }}` genuinely centers the title: the built-in `font-weight`/`font-size`/`padding` are removed for that slot, leaving your class in full control. ## Per-slot inline styles For one-off tweaks without a stylesheet, use `styles`. These merge **last**, on top of the retained defaults (and win over classes): ```tsx theme={null} import { MonthView } from "@super-calendar/dom"; ; ``` ## React Native (uniwind / NativeWind) The native renderer accepts the same `classNames` / `styles` maps with the same contract. Class strings pass through to the underlying `View`/`Text` elements, where a Tailwind runtime resolves them; the library ships TypeScript source through the `react-native` export condition, so your bundler compiles it with your Tailwind setup. Without such a runtime, `className` is ignored and `styles` still works. With [uniwind](https://docs.uniwind.dev), no extra configuration is needed beyond its quickstart; classes you pass from your app code are picked up by Tailwind's automatic content scanning: ```tsx theme={null} import { Calendar } from "@super-calendar/native"; ; ``` Differences from the web renderer: * **No `data-*` state variants.** React Native has no CSS selectors; state styling (today, selected) stays with the [theme](/guides/theming), or replace the part with a custom renderer. * **Slot names differ where the structure does.** Native adds text slots (`dayBadgeText`, `columnHeaderDateText`) because text colour doesn't inherit from a parent view, plus `weekendShade` and `daySeparator` for layers the dom styles through `dayColumn`. It omits dom-only slots (`dayColumn`, `events`, `chipButton`, `chip`, `eventBox`). * **Event chips and cards are `renderEvent`'s job.** To restyle them with Tailwind, pass your own `renderEvent` (or `renderMonthEvent` etc.) built from classed components. * **Animated slots.** `businessHours`, `weekendShade`, `daySeparator`, `event`, `nowIndicator`, and `createGhost` render as Reanimated views. Their `styles` overrides always apply; whether `className` resolves there depends on your runtime's support for Animated components. * **Pass stable references.** Define the `classNames` / `styles` maps at module scope (or wrap them in `useMemo`). Inline literals still work, but they change identity on every render, so the calendar re-resolves its slots each time instead of skipping the work. ## State variants with `data-*` (web only) Day cells expose their state as present/absent `data-*` attributes, so you can style selection, today, and more with Tailwind variants or plain CSS — no JS: ```tsx theme={null} import { MonthView } from "@super-calendar/dom"; ; ``` On the month grid, day state sits on both the `day` cell and its `dayBadge`, so a variant works on either slot (e.g. `dayBadge: "data-[today]:bg-blue-600"`). | Attribute | On | Present when | | - | - | - | | `data-today` | day / badge / col | it is today | | `data-selected` | day / badge | the day is selected | | `data-range` | day / badge | the day is inside a selected range | | `data-weekend` | day / badge / col | the day is a weekend | | `data-outside` | day / badge | the day belongs to an adjacent month | | `data-disabled` | day / badge | the day is disabled (`min`/`maxDate`) | | `data-creating` | day / badge | the day is inside a drag-to-create span | | `data-drop` | day / badge | a dragged event would land on this day | | `data-events` | year day | the day holds at least one event | | `data-dragging` | time-grid event | the event is being dragged | Every slotted element also carries a stable `data-slot=""` attribute, handy for CSS selectors (`[data-slot="title"] { … }`) and for tests. ## Slots by component Each component keeps its own `className` / `style` props for the root element; the slots below target its inner parts. `Calendar` accepts every slot and forwards them to whichever view its `mode` renders. `MonthList` uses `weekdays` / `weekday` for its shared header and forwards the rest to each month's `MonthView`. ### MonthView Native's `MonthView` supports `title`, `weekdays`, `weekday`, `grid`, `week`, `day`, `dayBadge`, `dayBadgeText`, `rangeBand`, `more`, and `morePopover`. | Slot | Element | | - | - | | `title` | The "Month yyyy" heading | | `weekdays` | The weekday header row (grid container) | | `weekday` | Each weekday label | | `grid` | The month grid container | | `week` | Each week row | | `day` | Each day cell (picker button or events cell) | | `dayBadge` | The date badge/circle inside a day | | `rangeBand` | The selection band layer behind a day | | `events` | The event-chips column inside an events-mode cell | | `chipButton` | The button wrapping each event chip | | `chip` | The default event chip | | `more` | The "+N more" overflow row | | `morePopover` | The built-in overflow popover card | ### TimeGrid (week / day / N-day) Native's `TimeGrid` supports `header`, `weekNumber`, `columnHeader`, `columnHeaderWeekday`, `columnHeaderDate`, `columnHeaderDateText`, the `allDay*` slots, `hourGutter`, `hourLabel`, `gridLines`, `businessHours`, `backgroundEvent`, `weekendShade`, `daySeparator`, `event`, `nowIndicator`, and `createGhost`. The day-header row is a fixed 56px tall so the columns, the all-day band, and the hour column line up; keep custom `columnHeader` content within that height. | Slot | Element | | - | - | | `header` | The column-header row | | `columnHeader` | Each day's header button (`data-today`) | | `columnHeaderWeekday` | The weekday label in a header | | `columnHeaderDate` | The date badge in a header (`data-today`) | | `allDayLane` | The all-day row | | `allDayLabel` | The "all-day" gutter label (with `showAllDayLabel`) | | `allDayColumn` | Each day's all-day column | | `allDayEvent` | An all-day event button | | `hourGutter` | The hour-axis column | | `hourLabel` | Each hour label | | `dayColumn` | Each day column (`data-today`) | | `gridLines` | The hour/slot grid-line overlay | | `businessHours` | The closed-hours shade | | `backgroundEvent` | A `display: "background"` event's band | | `event` | A timed-event wrapper (`data-dragging`) | | `eventBox` | The default event box | | `nowIndicator` | The current-time line | | `createGhost` | The drag-to-create preview | | `eventActionsTrigger` | The web **Edit events** button | | `eventActionsList` | The web event chooser list | | `eventActions` | The web move and resize actions dialog | | `eventAction` | Each button in the actions dialog | ### Agenda (schedule) Native's `Agenda` supports `dayHeader`, `eventRow`, and `empty`. | Slot | Element | | - | - | | `dayHeader` | Each day's header | | `eventRow` | The button wrapping each event | | `event` | The default event card | | `empty` | The "No events" placeholder | ### YearView Both renderers support `grid`, `month`, `monthTitle`, `weekdays`, `weekday`, `week`, `day`, `dayBadge`, `rangeBand`, and `eventDot` (plus `dayText` on React Native). | Slot | Element | | - | - | | `grid` | The twelve-month container | | `month` | Each mini month | | `monthTitle` | A mini month's title | | `weekdays` | A mini month's weekday-initials row | | `weekday` | Each weekday initial | | `week` | Each week row of a mini month | | `day` | Each day cell | | `dayBadge` | The round today/selected highlight | | `rangeBand` | The selection band layer behind a day | | `eventDot` | The dot under a day that holds events | ### MonthList (scrolling picker) `weekdays` / `weekday` style the shared header; every `MonthView` slot above is forwarded to each rendered month. ## Combining with the theme Slots and the [theme](/guides/theming) compose. Reach for the theme to recolour the whole calendar in one place; reach for slot classes when you want Tailwind (or your design system) to own a specific part. A common setup: theme for palette, `classNames` for typography and state variants. # Theming Source: https://super-calendar.afonsojramos.me/guides/theming Colors, typography, dark mode, and business hours. ## Theme tokens Pass a `Partial` — anything you omit falls back to `defaultTheme`. ```tsx theme={null} ``` ### Color tokens Every coloured surface is a token, so the visual touches below are all yours to restyle. The names are shared by both renderers — the React Native theme nests them under `colors`, the dom theme (`DomCalendarTheme`) is flat. | Token | Colors | | - | - | | `text` / `textMuted` / `textDisabled` | Day numbers / hour & "+N more" labels / disabled & adjacent-month days | | `gridLine` | Hour lines, day separators, month-cell borders | | `surface` | Opaque surface behind the date-picker field and popover | | `weekendBackground` | Weekend column/cell tint | | `outsideHoursBackground` | Closed-hours shade (business hours) | | `hoverBackground` | Hover highlight behind a day (web/mouse only) | | `todayBackground` / `todayText` | Today badge fill / text | | `selectedBackground` / `selectedText` | Selected day & range-endpoint badge fill / text | | `rangeBackground` | The selected-range band | | `nowIndicator` | Current-time line | | `eventBackground` / `eventText` | Default event chip fill / text | Metric tokens cover the sizes: `rangeBandHeight` (the pill strip's height; its corner radius is half this), the day-badge size/radius, and on dom `cellHeight` and `fontFamily`. See `CalendarTheme` / `DomCalendarTheme` for the exact types. The time-grid column header is fully themeable on React Native: `text.dayNumber` (the day number), `text.columnHeaderWeekday` (the weekday label; include a `color` to override the muted default), and the `columnHeader` / `columnHeaderBadge` containers below. Combined with `onPressDateHeader`, this lets an app restyle the built-in header instead of replacing it via `renderTimeGridHeader`. ### Container styles (React Native) Beyond text and colours, the React Native theme takes a `containers` map of `ViewStyle` overrides for the renderer's container elements — the native counterpart of the web renderer's per-slot [classes](/guides/styling). Each is merged onto the built-in style, so you set only what you need: ```tsx theme={null} ``` Available slots: | Slot | Element | | - | - | | `monthContainer` | The month view's outer container | | `weekdayHeader` | The weekday-label header row | | `weekRow` | Each week (row of 7 day cells) | | `dayCell` | Each day cell in the month grid | | `dayBadge` | The date badge (circle) inside a day | | `monthEvent` | An event chip inside a month day cell | | `columnHeader` | Each day's column header in the time grid | | `columnHeaderBadge` | The day-number badge (circle) in that header | | `timeGridEvent` | A timed event's positioned box | | `nowIndicator` | The current-time indicator line | | `agendaList` / `agendaRow` | The schedule list and each of its event rows | | `allDayLane` / `allDayColumn` | The all-day lane and each day's column in it | The date selection in [`MonthList`](/guides/month-list) draws filled endpoint badges (`selectedBackground` / `selectedText`) and a rounded band across the span (`rangeBackground`, height `rangeBandHeight`). The band caps at the endpoint circles; pass `fillCellOnSelection` to fill the whole cell instead of the pill. ### Dark mode A ready-made `darkTheme` is included. Switch on the system scheme with `useColorScheme()`: ```tsx theme={null} import { Calendar, darkTheme, defaultTheme } from "@super-calendar/native"; import { useColorScheme } from "react-native"; const scheme = useColorScheme(); ; ``` ### Reading the theme Inside a custom `renderEvent` (or any descendant), read the active theme with `useCalendarTheme()`. ### Tailwind & per-part classes (web) The theme recolours everything at once. To hand a specific part of the **web** calendar to Tailwind or your own CSS (with `data-*` state variants like `data-[today]:`), use per-slot `classNames` / `styles` — see [Styling with Tailwind & CSS](/guides/styling). ## Business hours Pass `businessHours` to tint the closed hours on the week/day grid. It's a function of the day, so open hours can vary and weekends can read as closed: return `{ start, end }` (hours, fractions allowed) to shade outside that range, or `null` to shade the whole day. The tint is the theme's `outsideHoursBackground`. ```tsx theme={null} { const weekday = date.getDay(); if (weekday === 0 || weekday === 6) return null; // weekends closed return { start: 9, end: 17 }; }} /> ``` ## Per-date column styling For shading specific dates (holidays, the selected day) across month cells and week/day columns, use `calendarCellStyle` — a function of the date returning a style. Unlike `businessHours` (which shades a time band), this tints the whole day. # Time grid Source: https://super-calendar.afonsojramos.me/guides/time-grid The week, day, 3-day, and custom hour-by-hour views. > [!NOTE] > > Examples use the React Native `Calendar`; most props are shared with the dom renderer, and the > [dom vs native comparison](/reference/renderers) lists what differs per renderer. `mode="week"`, `day`, `3days`, and `custom` all render the time grid: one column per day, hours down the side, events as positioned boxes, and an all-day lane on top. On React Native the day header and the all-day lane page with the columns while the hour column stays fixed on the left, so the whole grid moves as one when you swipe. `week` pages by the calendar week (set `weekStartsOn`: 0 = Sunday, 1 = Monday, and so on); `day` and `3days` page by their column count; [`custom`](/guides/views#custom-day-counts) renders any slice you choose. ```tsx theme={null} ``` `scrollOffsetMinutes` is applied on mount and again whenever its value changes, at the current zoom. Keep it stable rather than deriving it from the clock on every render: re-rendering with the same value leaves the user's scroll position alone, while a new value scrolls. ## Scroll to a time To scroll on demand, such as from a "now" button, attach a ref to `Calendar` (or `TimeGrid`) and call `scrollToTime` with minutes from midnight. Unlike `scrollOffsetMinutes`, it scrolls every time you call it, even to the same time. The scroll animates unless you pass `{ animated: false }` or the OS asks to reduce motion, and it does nothing while a month, year, or schedule view is showing. ```tsx theme={null} import { useRef, useState } from "react"; import { Button } from "react-native"; import { Calendar, type CalendarEvent, type CalendarHandle } from "@super-calendar/native"; function WeekWithNowButton({ events }: { events: CalendarEvent[] }) { const [date, setDate] = useState(new Date()); const calendar = useRef(null); const scrollToNow = () => { const now = new Date(); calendar.current?.scrollToTime(now.getHours() * 60 + now.getMinutes()); }; return ( <>