Skip to content

Latest commit

 

History

History
168 lines (142 loc) · 9.39 KB

README.md

File metadata and controls

168 lines (142 loc) · 9.39 KB
Raw

react-alternating-timeline

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

Demonstration

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 📚