Skip to content
Branch: master
Go to file

Latest commit

aaron9000 committed f74ec8d Jun 10, 2020
Merge pull request #27 from aaron9000/dependabot/npm_and_yarn/websock…

Bump websocket-extensions from 0.1.3 to 0.1.4


Failed to load latest commit information.
Latest commit message
Commit time


React Image Timeline

An image-centric timeline component for React.js. View chronological events in a pleasant way.

View Sample Timeline


  • Responsive layout
  • Graceful handling of non-uniform content
  • Customizable (use your own CSS and components)
  • Memoized, pure, & typed (Typescript definitions included)
  • Only 32kb
  • Zero extra dependencies


How to Use

npm install react-image-timeline --save

import React from 'react';
import ReactDOM from 'react-dom';
import Timeline from 'react-image-timeline';
require('react-image-timeline/dist/timeline.css'); // .scss also available

const events = [
        date: new Date(2013, 9, 27),
        text: "Sed leo elit, pellentesque sit amet congue quis, ornare nec lorem.",
        title: "Cairo, Egypt",
        buttonText: 'Click Me',
        imageUrl: "",
        onClick: console.log,

ReactDOM.render(<Timeline events={events} />, document.getElementById('root'));


Custom Styles

To customize the timeline, add your own CSS to override the default styles.

Event Metadata

To pass extra data into custom components, use extras on TimelineEvent.

Custom Dot Pattern

The dots are defined in CSS using a base64-encoded image. Encode a new image and override the corresponding CSS class.

Custom Components

For more advanced customization, you can pass in custom components to replace the defaults. Custom components will be passed a TimelineEvent model in props.

const CustomHeader = (props) => {

    const {title, extras} = props.event;
    const {customField} = extras;

    return <div className="custom-header">

ReactDOM.render(<Timeline events={events} customComponents={{header: CustomHeader}}/>, document.getElementById('root'));

Run Example Project (you will need create-react-app to run)

*install create-react-app*
*clone repository*
yarn --debug
yarn start

Run Tests

*clone repository*
yarn test

TypeScript & Models

Typescript definitions are included in the library.

Importing TypeScript Definitions

import {
} from 'react-image-timeline';


export interface TimelineProps {
    customComponents?: TimelineCustomComponents | null;
    events: Array<TimelineEvent>;
    reverseOrder?: boolean;
    denseLayout?: boolean;
Key Type Required?
events Array Yes
customComponents TimelineCustomComponents
reverseOrder boolean
denseLayout boolean


export interface TimelineCustomComponents {
    topLabel?: React.PureComponent<TimelineEventProps> | React.ReactNode | null;
    bottomLabel?: React.PureComponent<TimelineEventProps> | React.ReactNode | null;
    header?: React.PureComponent<TimelineEventProps> | React.ReactNode | null;
    imageBody?: React.PureComponent<TimelineEventProps> | React.ReactNode | null;
    textBody?: React.PureComponent<TimelineEventProps> | React.ReactNode | null;
    footer?: React.PureComponent<TimelineEventProps> | React.ReactNode | null;
Key Type Required?
topLabel component
bottomLabel component
header component
imageBody component
textBody component
footer component


export interface TimelineEventProps {
    event: TimelineEvent;
Key Type Required?
event TimelineEvent Yes


export interface TimelineEvent {
    date: Date;
    title: string;
    imageUrl: string;
    text: string;
    onClick?: TimelineEventClickHandler | null;
    buttonText?: string | null;
    extras?: object | null;
Key Type Required?
date date Yes
title string Yes
imageUrl string Yes
text string Yes
onClick function
buttonText string
extras object
You can’t perform that action at this time.