react-alternating-timeline

A simple and compact, true masonry style alternating timeline react component which is fully customizable and free stylable.

Features

• 🎛️ Customize everything.
• 🎨 Consistent (BEM) class naming for easy styling with CSS, emotion...
• ⏰ Custom date formatting.
• ⚖️ Alternating, left or right positioning.
• 🖼️ Render images and custom content.
• 🪄 Built with Typescript.

Installation

Add the package with the package manager via NPMs or GitHubs registry of choice to your project:

• yarn: yarn add react-alternating-timeline
• npm: npm install react-alternating-timeline
• pnpm: pnpm add react-alternating-timeline
• npx: npx -p react-alternating-timeline

Usage

import { Timeline, TimelineItemsProps } from 'react-alternating-timeline';

const items: TimelineItemsProps = [
  {
    key: 'first',
    date: new Date(),
    title: 'Special event!',
  },
  {
    key: 'second',
    date: new Date(),
    title: 'Event',
    children: <img src="./test.jpg" alt="test" />,
  },
  ...
];

<Timeline items={items} />;

API

The available properties of the Timeline component:

| Property | Type | Description | Default | | :--------------- | :------------------------------------------ | :---------------------------------------------------------------------------- | :-------------- | | items | TimelineItemsProps | Array of timeline items | | | positioning? | 'alternating' \| 'left' \| 'right' | How the items should be positioned relative to the timeline | 'alternating' | | minMarkerGap? | number | The minimum gap markers will have between each other | 50 (px) | | formatDate? | (date: Date) => string | Callback to format date | | | customMarker? | ReactElement | Custom maker element replacing the default | | | customPointer? | ReactElement | Custom pointer element replacing the default | | | styleConfig? | StyleConfig | Style config object for customizing timeline by setting css custom properties | | | className? | string | Additional class name | |

TimelineItemsProps

An array of the following properties:

| Property | Type | Description | | :--------------- | :----------------------- | :------------------------------------------------------------------------------- | | key | Key | Unique key for each item | | title? | string | Optional title paragraph displayed bold | | date | Date \| string | Date either being formatted according to provided format or passed as a string | | children? | ReactNode | Pass custom content as children to the component | | formatDate? | (date: Date) => string | Callback to format date of specific item | | customMarker? | ReactElement | Overwriting customMarker property of parent Timeline | | customPointer? | ReactElement | Overwriting customPointer property of parent Timeline |

Styling

The style can either be passed as an object through the styleConfig property...

{
  line?: {
    width?: CSSProperties['width'];
    color?: CSSProperties['backgroundColor'];
    overhang?: CSSProperties['paddingBlock'];
  };
  item?: {
    gap?: CSSProperties['gap'];
    startOffset?: {
      left?: CSSProperties['marginTop'];
      right?: CSSProperties['marginTop'];
    };
  };
  marker?: {
    size?: CSSProperties['width'];
    color?: CSSProperties['backgroundColor'];
    radius?: CSSProperties['borderRadius'];
  };
  pointer?: {
    height?: CSSProperties['height'];
    width?: CSSProperties['width'];
    minOffset?: CSSProperties['marginTop'];
  };
  card?: {
    background?: CSSProperties['backgroundColor'];
    radius?: CSSProperties['borderRadius'];
    shadow?: CSSProperties['boxShadow'];
    padding?: CSSProperties['padding'];
    offset?: CSSProperties['gap'];
  };
}

...or can be set as custom properties directly in css

.timeline {
  --line-width: 0.2rem;
  --line-color: black;
  --line-overhang: 1rem;
  --item-gap: 1rem;
  --item-start-offset-left: 0;
  --item-start-offset-right: 5rem;
  --marker-size: 1rem;
  --marker-color: var(--line-color);
  --marker-radius: 50%;
  --pointer-height: 2rem;
  --pointer-width: 1rem;
  --pointer-min-offset: 5rem;
  --card-background: whitesmoke;
  --card-radius: 0.1rem;
  --card-shadow: unset;
  --card-padding: 1rem;
  --card-offset: 1rem;
}

StyleConfig

| Name | Description | Default | | :------------------------- | :------------------------------------------------------------------------------------------------------------- | :------------ | | Line | The line the timeline items are place around/beside | | | – line-width | Width of the line | 0.2rem | | – line-color | Color of the line | black | | – line-overhang | How much the line should overhang the beginning and end of the timeline component | 1rem | | Item | The timeline item as a whole, including the card, pointer and marker | | | – item-gap | The vertical space between the items | 1rem | | – item-start-offset-left | How much the items on the left side should be offset from the top | 0 | | – item-start-offset-left | How much the items on the right side should be offset from the top | 5rem | | Marker | The markers on the line which marks the chronological order of the timeline items | 1rem | | – marker-size | Size of the default marker | 1rem | | – marker-color | Color of the default marker | line-color | | – marker-radius | Border radius (roundness) of the marker edges | 50% (round) | | Pointer | The pointers pointing from the item cards to the markers on the line | | | – pointer-height | Height of the default pointer | 2rem | | – pointer-width | Width of the default pointer | 1rem | | – pointer-min-offset | Minimum offset of the pointer to the top of the card. The actual offset depends on the minMarkerGap property | 5rem | | Card | The cards in which the timeline item content is displayed | | | – card-background | Background color of the card | whitesmoke | | – card-radius | Border radius of the card edges | 0.1rem | | – card-shadow | Configure drop shadow of the card | unset | | – card-padding | Padding of the card content | 1rem | | – card-offset | Space between the card and the timeline line | 1rem |

Demo

View a full demo of component as storybook: Storybook 📚