Guides
Loading Events
Fetch events for the dates on screen as people navigate, and show a loading bar while they arrive.
The calendar doesn't fetch anything itself. onVisibleRangeChange tells you which dates are on screen, every time they change, so you can load the events for them. While you do, loading draws a thin bar under the day headers. In the preview, a pretend server answers after 800ms. Navigate, switch views or scroll sideways, and watch the log: a range seen before comes from the cache, with no bar.
Usage
Keep the events in state, fetch them in onVisibleRangeChange, and pass loading while a request is in flight:
import { CalendarProvider } from "@/components/calendar-provider";
import { WeekView } from "@/components/week-view";
import type { CalendarEvent, VisibleRange } from "@/components/calendar-types";
export function Schedule() {
const [events, setEvents] = React.useState<CalendarEvent[]>([]);
const [loading, setLoading] = React.useState(false);
const latestRequest = React.useRef(0);
const loadRange = React.useCallback(async (range: VisibleRange) => {
const request = ++latestRequest.current;
setLoading(true);
const next = await getEvents(range.start, range.end); // your API
// People may have moved on while this was loading
if (request !== latestRequest.current) return;
setEvents(next);
setLoading(false);
}, []);
return (
<CalendarProvider
events={events}
onEventsChange={setEvents}
onVisibleRangeChange={loadRange}
loading={loading}
>
<WeekView />
</CalendarProvider>
);
}With a data library such as TanStack Query, keep the range in state, use it as the query key, and pass isFetching as loading. Save drags, resizes and edits in onEventUpdate, and update the query's cache so they stick.
const [range, setRange] = React.useState<VisibleRange | null>(null);
const { data: events = [], isFetching } = useQuery({
queryKey: ["events", range?.start.toISOString(), range?.end.toISOString()],
queryFn: range ? () => getEvents(range.start, range.end) : skipToken,
placeholderData: keepPreviousData,
});
<CalendarProvider
events={events}
onVisibleRangeChange={setRange}
onEventUpdate={saveEvent}
loading={isFetching}
>
<WeekView />
</CalendarProvider>;The Calendar block takes every CalendarProvider prop and passes it through, so onVisibleRangeChange and loading work on it the same way:
<Calendar
events={events}
onEventsChange={setEvents}
onVisibleRangeChange={loadRange}
loading={loading}
/>The range
start is midnight at the beginning of the first visible day, and end is midnight after the last one, so end is exclusive. Both are in the viewer's time zone. With timeZone on the provider, they are the instants those midnights fall on in that zone.
| View | Range | Example, week of Thursday Jun 4 2026 |
|---|---|---|
| Day | The day on screen | Jun 4 → Jun 5 |
| Week | numberOfDays days from the first column, 7 by default | May 31 → Jun 7 |
| Month | The whole six-week grid, days from the months before and after included | May 31 → Jul 12 |
| Agenda | The 30 days it lists, from its first day | Jun 4 → Jul 4 |
| Year | The whole year, January 1 to the next January 1 | Jan 1 2026 → Jan 1 2027 |
When weekends are hidden, day and week view report the weekdays they draw: a week runs from Monday to Friday, so the range ends on Saturday's midnight. Month view's range starts and ends on the first and last weekday it shows. The agenda's range keeps its weekend days; it only leaves them out of its list.
An event belongs in the range when it starts before end and ends after start:
const inRange = (event: CalendarEvent, range: VisibleRange) =>
event.start < range.end &&
(event.isAllDay ? event.end >= range.start : event.end > range.start);All-day events
An all-day event's end is the start of its last day, so a one-day event has start equal to end. Compare its end with >=, or it drops off the first day of the range.
Read the range anywhere inside the provider with useCalendar().visibleRange, and the loading state with useCalendar().loading, for example to show a spinner in your own toolbar.
When it fires
- Once after the view mounts.
- When the dates change: previous and next, today,
goToDate, a view switch, a newnumberOfDays, and month view's vertical scroll. - During a sideways scroll in day and week view, once the scroll snaps to a day, not for every day it passes. For the days on screen mid-scroll, read
visibleDays. - Never twice in a row for the same range. Re-renders, edits and selection don't fire it, and neither does a view switch that's undone because the mounted view doesn't follow it.
A range can come back: going to next week and back reports this week again. Cache by range, as the preview does, or by day, so a range seen before skips the network.
Loading bar
loading draws a 2px indeterminate bar along the bottom of the day headers in Day View, Week View and Month View, and along the top of Agenda View and Year View. It doesn't block anything: people can keep dragging, creating and navigating while events load. With reduced motion turned on, the bar holds still instead of sliding. The view is marked aria-busy while loading.
The bar is CalendarLoadingBar in components/calendar-loading-bar.tsx, and its animation is a .calendar-loading-bar class. Both come with Calendar Core, so every view you install has it.
API Reference
The provider props and the range type. See Calendar Core for the rest of the provider.
| Prop | Type | Default |
|---|---|---|
onVisibleRangeChangeCalled with the dates the view draws: once after it mounts, then each time they change. Never twice in a row for the same range. | (range: VisibleRange) => void | – |
loadingShows a thin progress bar under the day headers of every view. The calendar stays usable. | boolean | false |
VisibleRange
| Field | Type |
|---|---|
startMidnight that starts the first visible day. | Date |
endMidnight after the last visible day (exclusive). | Date |