Registry /
web-framework / react-calendar-timeline
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Timeline
✓ import Timeline from 'react-calendar-timeline'
✗ const Timeline = require('react-calendar-timeline')
The library primarily targets ESM imports since v0.30.0-beta.1 due to the TypeScript rewrite and Vite bundling. CommonJS `require()` may not function correctly without specific transpilation.
TimelineMarkers
✓ import { TimelineMarkers, TodayMarker, CursorMarker, CustomMarker } from 'react-calendar-timeline'
✗ import TimelineMarkers from 'react-calendar-timeline/lib/markers'
Marker components are exported as named exports directly from the main package. Older versions might have used different, more granular import paths.
TimelineHeaders
✓ import { TimelineHeaders, SidebarHeader, DateHeader } from 'react-calendar-timeline'
✗ import TimelineHeaders from 'react-calendar-timeline/headers'
Header components are named exports. Direct sub-path imports (e.g., '/lib/headers') are generally not necessary in current major beta versions.
ReactCalendarTimelineProps
✓ import type { ReactCalendarTimelineProps } from 'react-calendar-timeline'
Type imports for defining component props. The library ships with TypeScript types since v0.30.0-beta.1, providing strong typing for usage.
This quickstart demonstrates a basic `react-calendar-timeline` setup with two groups, three items, and custom headers. It showcases initial rendering, basic interaction (move, resize, change group), and marker usage within a TypeScript React component.
import React from 'react';
import dayjs from 'dayjs';
import Timeline, { TimelineHeaders, SidebarHeader, DateHeader, TodayMarker } from 'react-calendar-timeline';
interface MyItem {
id: number;
group: number;
title: string;
start_time: dayjs.Dayjs;
end_time: dayjs.Dayjs;
}
interface MyGroup {
id: number;
title: string;
}
const groups: MyGroup[] = [
{ id: 1, title: 'Group One' },
{ id: 2, title: 'Group Two' }
];
const items: MyItem[] = [
{ id: 1, group: 1, title: 'Item 1', start_time: dayjs().add(-1, 'hour'), end_time: dayjs().add(1, 'hour') },
{ id: 2, group: 2, title: 'Item 2', start_time: dayjs().add(-3, 'hours'), end_time: dayjs().add(-1, 'hour') },
{ id: 3, group: 1, title: 'Item 3', start_time: dayjs().add(2, 'hours'), end_time: dayjs().add(4, 'hour') }
];
const TimelineExample: React.FC = () => {
const defaultTimeStart = dayjs().add(-12, 'hour').toDate();
const defaultTimeEnd = dayjs().add(12, 'hour').toDate();
return (
<Timeline
groups={groups}
items={items}
defaultTimeStart={defaultTimeStart}
defaultTimeEnd={defaultTimeEnd}
canMove={true}
canResize={'right'}
canChangeGroup={true}
>
<TimelineHeaders className="sticky">
<SidebarHeader>
{({ get}) => {
return <div {...get('sidebarProps')}>My Custom Sidebar</div>;
}}
</SidebarHeader>
<DateHeader unit="primaryHeader" />
<DateHeader />
</TimelineHeaders>
<TodayMarker />
</Timeline>
);
};
export default TimelineExample;
Debug
Known issues
breakingVersion 0.30.0-beta.1 introduced a major breaking change with a full rewrite to TypeScript, migration to Vite for bundling, and updated peer dependencies to React 18+ and Day.js 1.11.10+. Projects using older React versions or relying on CommonJS without proper transpilation will require significant updates.fixUpgrade your React project to React 18+ and ensure your build pipeline supports ESM modules and TypeScript. Verify `dayjs` is at `^1.11.10`. Adjust import statements to named exports where applicable.
affects: >=0.30.0-beta.1
gotchaThe timeline's resize detection mechanism was overhauled in v0.30.0-beta.13, transitioning from `window.resize` events to native `ResizeObserver`. While this resolves many long-standing issues with container-level width changes, developers with custom resize handlers or those relying on the prior `window.resize` behavior might observe different or improved responsiveness.fixReview any custom resize logic; it may no longer be necessary or could conflict with the native `ResizeObserver` implementation. The new approach typically handles resizing automatically.
affects: >=0.30.0-beta.13
gotchaFrom v0.30.0-beta.15, Safari trackpad scroll jank was addressed by replacing native `scrollLeft` with CSS `transform: translateX()`. This is an internal performance enhancement, but could potentially interact unexpectedly with highly customized scroll event handlers or CSS overrides that directly manipulate scroll properties.fixMost users will experience improved scroll performance. If unexpected scroll behavior occurs in highly customized setups, inspect CSS `transform` properties and `onScroll` event handlers for conflicts.
affects: >=0.30.0-beta.15
gotchaPrior to v0.30.0-beta.14, `getItemProps` within a custom `itemRenderer` silently dropped custom event handlers (`onClick`, `onMouseEnter`, etc.) and generic HTML attributes. This issue has been fixed, meaning these properties are now correctly forwarded. If developers implemented manual workarounds for this, those workarounds might now be redundant or conflict with the corrected behavior.fixRemove any custom workarounds implemented to forward event handlers or HTML attributes that `getItemProps` should handle. Rely on `getItemProps` for correct property forwarding.
affects: >=0.30.0-beta.14
Errors
Common errors & fixes
Timeline markers (TodayMarker, CursorMarker, CustomMarker) becoming invisible
In versions prior to 0.30.0-beta.16, markers could render with zero height due to `MarkerCanvas` being `position: absolute` combined with internal transform changes, causing markers with `top:0; bottom:0` to collapse.
fixUpgrade `react-calendar-timeline` to `0.30.0-beta.16` or higher, which includes a fix for this issue. Also, ensure no conflicting CSS is overriding marker positioning or height.
TypeError: Cannot read properties of undefined (reading 'setState') or similar React compatibility errors.
Using `react-calendar-timeline` version `>=0.30.0-beta.1` with an incompatible React version (e.g., React 17 or older), as the library now requires React 18+.
fixUpdate your project's `react` and `react-dom` peer dependencies in `package.json` to `^18 || ^19.0.0-rc-66855b96-20241106` to meet the library's requirements.
Drag and drop or resize functionality on timeline items is not working as expected.
This can be caused by a missing or incorrect `interactjs` peer dependency, or the `canMove` and `canResize` props not being correctly set on the `Timeline` component.
fixEnsure `interactjs@1.10.27` is installed as a peer dependency. Verify `canMove={true}` and `canResize={'left' | 'right' | 'both' | true}` are explicitly passed to the `Timeline` component as required for desired interactions. Upgrade
Version history
0.30.0-beta.4latest on npm
Audit
Dependencies
dayjsrequiredUsed for date and time manipulation within the timeline's logic.
reactrequiredCore React library for building the user interface. Requires React 18 or 19.
react-domrequiredProvides DOM-specific rendering methods for React components. Requires React 18 or 19.
interactjsrequiredPowers the drag-and-drop, resize, and multi-touch gesture functionality for timeline items.