@alessandro-lenzi/react-timeline

A vertical timeline with dynamic table of contents, for React.js, with motion animations.

Warning: This is a work in progress and it's not perfect ;P.

Sample:

Installation:

npm i @alessandro-lenzi/react-timeline

Basic component structure:

import { Timeline } from '@alessandro-lenzi/react-timeline';

<Timeline
  entries={[
    {
      date: string | Date;
      ...
    }
  ]}
/>

Parameters:

Parameter	Type	Default	Required	Description
entries	TimelineEntry	Default	Required	List of chronological entries for the timeline. See TimelineEntry specs below.
renderContent	(entry: TimelineEntry) => ReactNode		Optional	Function to render each entry row on the timeline.
mode	'single' | 'split'	'split'	Optional	Function to render each entry row on the timeline.
align	'center' | 'left' | 'right'	'center'	Optional	Place where the vertical bar will appear. Note the 'center' is only available when mode == 'split'.
renderDetail	(entry: TimelineEntry) => ReactNode		Required when 'split' mode	Function to render each entry's row detail (second column content). Required when mode == 'split'.

Entry properties: TimelineEntry<T>

Parameter	Type	Default	Required	Description
date	Date | string		Required	Date value used for chronological sorting.
icon	string | ReactNode		Optional	Icon to be used for this entry.
title	string		Optional	Entry title. (Optional so you can use your custom renderContent)
description	string		Optional	Entry description. (Optional so you can use your custom renderContent)
[string]	any		Optional	You can add any other fields, so they can be used on your custom renderContent and renderDetail

So, in case you have custom fields such as detail: string and a bigDescription: string, you can define as follow:

interface MyCustomFields {
  detail: string;
  bigDescription: string;
}
const myentries: TimelineEntry<MyCustomFields> = [
  {
    date: '2025-01-01',
    ...,
    detail: 'My detail data here',
    bigDescription: 'My big description here',
  },
  ...
]

Usage example:

Dual column with bar in the middle:

        <Timeline
          renderDetail={(entry) => (
            <div className="flex flex-1 flex-col gap-2 rounded-md p-6">
              <div className="font-bold">{entry.detail}</div>
            </div>
          )}
          entries={[
            {
              date: new Date(2024, 5, 1),
              title: '2. My second row',
              description: breakLines(lorem.generateParagraphs(1)),
              detail: breakLines(lorem.generateSentences(2)),
            },
            {
              date: new Date(2024, 5, 2),
              title: '1. My first row at the top',
              description: breakLines(lorem.generateParagraphs(1)),
              detail: breakLines(lorem.generateSentences(2)),
            },
            {
              date: new Date(2023, 5, 4),
              title: '3. My third row',
              description: breakLines(lorem.generateParagraphs(1)),
              detail: breakLines(lorem.generateSentences(2)),
            },
            {
              date: new Date(2023, 5, 2),
              title: `5. ${lorem.generateSentences(1)}`,
              description: breakLines(lorem.generateParagraphs(1)),
              detail: breakLines(lorem.generateSentences(2)),
            },
            {
              date: new Date(2023, 5, 3),
              title: `4. ${lorem.generateSentences(1)}`,
              description: breakLines(lorem.generateParagraphs(1)),
              detail: breakLines(lorem.generateSentences(2)),
            },
            {
              date: new Date(2022, 5, 1),
              title: `8. ${lorem.generateSentences(1)}`,
              description: breakLines(lorem.generateParagraphs(1)),
              detail: breakLines(lorem.generateSentences(2)),
            },
            {
              date: new Date(2022, 5, 2),
              title: `7. ${lorem.generateSentences(1)}`,
              description: breakLines(lorem.generateParagraphs(1)),
              detail: breakLines(lorem.generateSentences(2)),
            },
            {
              date: new Date(2022, 5, 3),
              title: `6. ${lorem.generateSentences(1)}`,
              description: breakLines(lorem.generateParagraphs(1)),
              detail: breakLines(lorem.generateSentences(2)),
            },
            {
              date: new Date(2021, 5, 1),
              title: `12. ${lorem.generateSentences(1)}`,
              description: breakLines(lorem.generateParagraphs(1)),
              detail: breakLines(lorem.generateSentences(2)),
            },
            {
              date: new Date(2021, 5, 2),
              title: `11. ${lorem.generateSentences(1)}`,
              description: breakLines(lorem.generateParagraphs(1)),
              detail: breakLines(lorem.generateSentences(2)),
            },
            {
              date: new Date(2021, 5, 3),
              title: `10. ${lorem.generateSentences(1)}`,
              description: breakLines(lorem.generateParagraphs(1)),
              detail: breakLines(lorem.generateSentences(2)),
            },
            {
              date: new Date(2021, 5, 4),
              title: `9. ${lorem.generateSentences(1)}`,
              description: breakLines(lorem.generateParagraphs(1)),
              detail: breakLines(lorem.generateSentences(2)),
            },
          ]}
        />