Introducing react-chrono - A flexible Timeline component for React
Tags: react, typescript, opensource, webdev
Published: 2020-09-18 17:01:12

Introducing **react-chrono**, a flexible timeline component built for React.

![app-home](https://dev-to-uploads.s3.amazonaws.com/i/g3i40kmmhbncabzvadgh.png)

[Fork this Repository](https://github.com/prabhuignoto/react-chrono)

[Demos](https://react-chrono.vercel.app/)

{% github prabhuignoto/react-chrono no-readme %}
 
## Features

✅ **Modes** - Render timelines in three unique modes `horizontal`, `vertical` or `tree`.

✅ **Tree** - Use the `Tree` mode to layout timeline cards vertically in a tree like fashion.

✅ **Slideshow** - Auto play the timeline in `slideshow` mode.

✅ **Keyboard Support** - Navigate the timelines using <kbd>UP</kbd> , <kbd>DOWN</kbd> keys in `vertical` or `tree` mode. In `horizontal` mode <kbd>LEFT</kbd> , <kbd>RIGHT</kbd> keys can be used.

✅ **Custom theme** - Customize the colors using the `theme` prop

## Installation

```sh
yarn install react-chrono
```

## 🚀 Getting Started

Please make sure you wrap the component in a container that has a `width` and `height`. When no `mode` is specified, the component defaults to `HORIZONTAL` mode.

Use the `items` prop to create the timeline. Each Timeline item have the following properties.

`title`, `contentTitle`, `contentText`, `contentDetailedText`

Here is an example Timeline with minimal settings.

```sh
  const items = [{
    title: "May 1940",
    contentTitle: "Dunkirk",
    contentText:"Men of the British Expeditionary Force (BEF) wade out to a destroyer during the evacuation from Dunkirk.",
    contentDetailedText: "On 10 May 1940, Hitler began his long-awaited offensive in the west...",
  }, ...];

  <div style={{ width: "500px", height: "400px" }}>
    <chrono items={items} />
  </div>
```

![app-home](https://dev-to-uploads.s3.amazonaws.com/i/g3i40kmmhbncabzvadgh.png)
 
### Vertical

To render the timeline vertically use the `VERTICAL` mode

```sh
  <div style={{ width: "500px", height: "950px" }}>
    <chrono
      items={items}
      mode="VERTICAL"
    />
  </div>
```
![vertical](https://dev-to-uploads.s3.amazonaws.com/i/vupx8hqds7skb4kjvec2.png)
 

### Tree

In `Tree` mode the timeline is rendered vertically with cards alternating between left and right sides.

```sh
  <div style={{ width: "500px", height: "950px" }}>
    <chrono
      items={items}
      mode="TREE"
    />
  </div>
```

![app-tree](https://dev-to-uploads.s3.amazonaws.com/i/dzvozf43ywfbwu5aetgq.png)

### Slideshow

Play the timeline automatically with the `slideShow` mode.

```sh
  <div style={{ width: "500px", height: "950px" }}>
    <chrono
      items={items}
      slideShow
    />
  </div>
```

![demo](https://dev-to-uploads.s3.amazonaws.com/i/5gvptdl8oymyv0fizd90.gif)
 

**Try it on CodeSandbox!**

[![Edit react-chrono](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/react-chrono-bg56e?fontsize=14&hidenavigation=1&theme=dark)

## Props

| name              | description                                                                           | default      |
| ----------------- | ------------------------------------------------------------------------------------- | ------------ |
| mode              | sets the layout for the timeline component. can be `HORIZONTAL`, `VERTICAL` or `TREE` | `HORIZONTAL` |
| items             | collection of timeline items                                                          | []           |
| disableNavOnKey   | disables keyboard navigation                                                          | false        |
| slideShow         | starts the timeline in slideshow mode                                                 | false        |
| slideItemDuration | The amount of delay in `ms` for the timeline points in `slideshow` mode               | 2500         |
| titlePosition     | sets the position of the title in `HORIZONTAL` mode. can be `TOP` or `BOTTOM`         | `TOP`        |
| itemWidth         | width of the timeline section in `HORIZONTAL` mode                                    | 320          |

### Mode

`react-chrono` supports three modes `HORIZONTAL`, `VERTICAL` and `TREE`. The mode prop can be used to define the orientation of the cards.

### Keyboard Navigation & Disabling it

The timeline by default can be navigated via keyboard.

- For `HORIZONTAL` mode use your <kbd>LEFT</kbd> <kbd>RIGHT</kbd> arrow keys for navigation.
- For `VERTICAL` or `TREE` mode, the timeline can be navigated via the <kbd>UP</kbd> <kbd>DOWN</kbd> arrow keys.
- To easily jump to the first item or the last item in the timeline, use <kbd>HOME</kbd> or <kbd>END</kbd> key.

The keyboard navigation can be completely disabled by setting the `disableNavOnKey` to true.

```sh
  <chrono items={items} disableNavOnKey />
```

### Slideshow Mode

Slideshow can be enabled by setting the `slideShow` prop to true. You can also set an optional `slideItemDuration` that sets the time delay between cards.

```sh
  <chrono items={items} slideShow slideItemDuration={4500} />
```

### Title Position

This setting only applies for the `HORIZONTAL` mode. The prop `titlePosition` sets the position of the individual titles to either `TOP` or `BOTTOM`.

```sh
  <chrono items={items}  titlePosition="BOTTOM" />
```

### Item Width

The `itemWidth` prop can be used to set the width of each individual timeline sections. This setting is applicable only for the `HORIZONTAL` mode.

## Built with

- [ReactJS](react) - The Component is written in React and [Typescript](typescript).

## Meta

Prabhu Murthy – [@prabhumurthy2](https://twitter.com/prabhumurthy2) – prabhu.m.murthy@gmail.com

Distributed under the MIT license. See `LICENSE` for more information.

[https://github.com/prabhuignoto/react-chrono](https://github.com/prabhuignoto/react-chrono)

<!-- Markdown link & img dfn's -->

[react]: https://reactjs.org
[typescript]: https://typescriptlang.org