@d3-timeline/react

A React component wrapper for the D3-based Timeline visualization component. It handles lifecycle management, reactivity, and provides an easy way to build custom event items using React components.

Installation

npm install @d3-timeline/react @d3-timeline/core

Basic Usage

Import the Timeline component and pass your array of event objects as well as a configuration object. The Timeline component expects you to render your custom items as its children using a render prop function.

import React, { useState } from 'react';
import Timeline from '@d3-timeline/react';
import '@d3-timeline/react/dist/style.css'; // Don't forget to import the CSS!

const App = () => {
  const [events] = useState([
    { id: "1", date: new Date("2023-01-15"), title: "Project Kickoff", description: "Initial team meeting." },
    { id: "2", date: new Date("2023-05-10"), title: "Alpha Release", description: "First working version." }
  ]);

  const config = {
    orientation: 'horizontal' // 'horizontal' or 'vertical'
  };

  return (
    <div style={{ height: '400px' }}>
      <Timeline 
        data={events} 
        config={config} 
        onSelected={(item) => console.log('Selected Event:', item)}
      >
        {(item) => (
          <div className="custom-event-card">
            <h3>{item.title}</h3>
            <p>{item.description}</p>
            <small>{item.date.toDateString()}</small>
          </div>
        )}
      </Timeline>
    </div>
  );
};

export default App;

Props

• data: An array of data objects. Each object must contain a valid date property (JavaScript Date object).
• config: A configuration object passed down to the core engine. You can configure orientation, custom collisionPriority, etc.
• onSelected: Optional callback function triggered when an event item is clicked.

Rendering Custom Items

The timeline uses a React render prop to let you render custom JSX for each event. Ensure the container has enough space to allow proper collision detection and element distribution.