react-calendar-timeline

The timeline requires a time range to function. You must provide one of the following sets of props:

1. defaultTimeStart and defaultTimeEnd: Specifies the initial time range. Accepts a Date or dayjs object.
2. visibleTimeStart and visibleTimeEnd: Specifies the exact viewport. These must be Unix timestamps in milliseconds. When using these, you must orchestrate scrolling via the onTimeChange function.

Note: If you use visibleTimeStart/End, the timeline will not automatically scroll; you must manage the state of the viewport yourself.

Users can navigate and manipulate the timeline view using the following keyboard and mouse combinations:

The timeline uses a high-performance scrolling mechanism. It renders a canvas that is 3x wider than the visible screen.

As the user scrolls, the library monitors the position. When the scroll reaches a threshold (50% of the invisible surface on one side), the library updates the position:absolute;left:{num}px; variables for all visible items and resets the canvas scroll position. This process triggers the onBoundsChange prop. This technique creates a visually endless scrolling effect with optimal performance.

The DateHeader uses a labelFormat prop to determine how time interval labels are displayed.

1. String Format: If a string is provided, it is passed directly to the format method of a dayjs object representing the startTime.

2. Function Format: A function provides maximum control. It receives the following arguments: ([startTime, endTime], unit, labelWidth, formatOptions) => string

Responsive Default Formatting: The library includes a default responsive formatting logic based on the labelWidth (the width of the interval in pixels). The format scales as follows:

• < 50px: short
• 50px - 100px: medium
• 100px - 150px: mediumLong
• > 150px: long

You can install the library using npm or yarn. Note that the 0.30.0 beta version is available via a specific tag.

Stable Version (0.28.0)

Use this if you are not ready to upgrade to the beta. It uses moment.js as its date library.

npm install react-calendar-timeline

Beta Version (0.30.0-beta)

Includes a full TypeScript rewrite, dayjs support, and React 18/19 support.

npm install react-calendar-timeline@beta

Peer Dependencies

Ensure you have the following peer dependencies installed:

• react
• react-dom
• dayjs (for 0.30.0+)
• interactjs

# via yarn
yarn add react-calendar-timeline

# via npm
npm install --save react-calendar-timeline

If you are upgrading from the 0.2x stable series to the 0.30.0 beta, note the following breaking changes:

• Date library: moment has been replaced with dayjs. Update your peer dependency and all date-related code.
• CSS import: Change 'react-calendar-timeline/lib/Timeline.css' to 'react-calendar-timeline/style.css'.
• React version: React 18+ is required (React 16/17 are no longer supported).
• ImmutableJS: Plain JavaScript arrays must be used; immutableJS arrays are no longer supported.
• TypeScript: Types are now bundled; you no longer need @types/react-calendar-timeline.
• Bundler: The package is now bundled with Vite instead of webpack/rollup.

If your timeline appears without styles, you must manually import the library's stylesheet into your application entry point.

import 'react-calendar-timeline/style.css'

To enable a right sidebar, you must configure both the <Timeline /> component and your group data:

1. Set the rightSidebarWidth prop on the <Timeline /> component.
2. Add a rightTitle property to each object in your groups array.

If you are using Custom Headers, you must also add a SidebarHeader component under the TimelineHeader with the variant="right" prop.

By default, the timeline detects window resizing. To detect when the component's own DOM element changes size, you must explicitly opt-in by passing a resizeDetector to the Timeline component. This is done to avoid including ~18kb of extra JS by default.

import containerResizeDetector from 'react-calendar-timeline/lib/resize-detector/container'

<Timeline resizeDetector={containerResizeDetector} ... />

To start the development server for the demo-next project, use your preferred package manager to run the dev script. Once running, the application will be available at http://localhost:3000.

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

When items are moved or resized, the timeline provides event objects that follow the OnItemDragObjectBase structure. You can distinguish between movement and resizing using the eventType field.

• Move Event: OnItemDragObjectMove contains the itemId, the new time, and the newGroupOrder.
• Resize Event: OnItemDragObjectResize contains the itemId, the new time, and the edge (the side being resized).