Get Started

Up and running with Tempis in a few minutes. Choose your path — use the core library directly, or drop in the React component.

Core Library

Install

Install the core library via npm:

$ npm install @tempis/timeline

CDN

Or include it directly in your HTML via a CDN script tag:

<script src="https://unpkg.com/@tempis/timeline/dist/tempis_timeline.min.js"></script>

Usage

Create a canvas element and initialise the timeline:

<canvas id="timeline"></canvas>

<script>
  import { TempisTimeline } from '@tempis/timeline';

  const timeline = new TempisTimeline('#timeline', {
    responsive: true,
    items: [
      { id: 1, label: 'Item 1', start: '2026-01-05', end: '2026-01-15', grouping: 'Group 1' },
      { id: 2, label: 'Item 2', start: '2026-01-12', end: '2026-01-28', grouping: 'Group 1' },
      { id: 3, label: 'Event 1', start: '2026-01-30', grouping: 'Group 1' },
      { id: 4, label: 'Item 3', start: '2026-01-08', end: '2026-01-25', grouping: 'Group 2' },
    ],
    range: { start: '2026-01-01', end: '2026-02-01', position: 'bottom' }
  });
</script>

When using responsive: true, the canvas must be inside a container with explicit dimensions. The timeline resizes to fill its parent — if the parent has no width or height, the canvas will collapse to zero.

Updating Data

Replace items, categories, or bands at any time — the timeline redraws automatically:

timeline.setItems(newItems);
timeline.setCategories(newCategories);
timeline.setBands(newBands);

Focus & Navigation

Programmatically pan and zoom to any item, date, or range:

// Animate to a specific item
timeline.focus({ id: 1, animate: true, duration: 500 });

// Jump to a date
timeline.focus({ date: '2026-06-15' });

// Focus on a date range
timeline.focus({ range: ['2026-01-01', '2026-12-31'], animate: true });

Cleanup

Always destroy the timeline when you're done to prevent memory leaks:

timeline.destroy();

React

Install

$ npm install @tempis/react @tempis/timeline

@tempis/timeline is a peer dependency and must be installed alongside the React wrapper.

Usage

Import the component and pass your data as props. The timeline renders into a canvas inside a wrapper div:

import { TempisTimeline } from '@tempis/react';

function App() {
  return (
    <TempisTimeline
      items={[
        { id: 1, label: 'Item 1', start: '2026-01-05', end: '2026-01-15', grouping: 'Group 1' },
        { id: 2, label: 'Item 2', start: '2026-01-12', end: '2026-01-28', grouping: 'Group 1' },
        { id: 3, label: 'Item 3', start: '2026-01-08', end: '2026-01-25', grouping: 'Group 2' },
      ]}
      options={{
        responsive: true,
        range: { start: '2026-01-01', end: '2026-02-01', position: 'bottom' }
      }}
      onItemClick={(id) => console.log('Clicked', id)}
      height={400}
    />
  );
}

When using responsive: true, the component must be inside a container with explicit dimensions. The timeline resizes to fill its parent — if the parent has no width or height, the canvas will collapse to zero.

Ref API

Access imperative methods via a ref:

import { useRef } from 'react';
import { TempisTimeline, type TempisTimelineRef } from '@tempis/react';

function App() {
  const ref = useRef<TempisTimelineRef>(null);

  return (
    <>
      <button onClick={() => ref.current?.focus({ id: 1, animate: true })}>
        Focus Item 1
      </button>
      <TempisTimeline
        ref={ref}
        items={items}
        options={{ responsive: true, range: { start: '2026-01-01', end: '2026-02-01', position: 'bottom' } }}
      />
    </>
  );
}

Reactive Data

The items, categories, and bands props sync automatically when they change — no manual setItems() calls needed.

const [items, setItems] = useState([
  { id: 1, label: 'Item 1', start: '2026-02-01', end: '2026-02-10' },
]);

// Adding an item re-renders the timeline automatically
setItems(prev => [...prev, { id: 2, label: 'Item 2', start: '2026-02-12', end: '2026-02-20' }]);

Next Steps

Explore the API reference for the full list of options, methods, and callbacks. Check out the interactive examples to see what's possible.

AI Context

Using an AI coding assistant? Download the full API reference as a single file for your AI agent to consume. Download llms.txt

Get Help

Got a question or found a bug? Open an issue or start a discussion on the Tempis GitHub repository.