0.0.9 • Published 1 year ago
react-timeline v0.0.9
React Timeline
A simple and customizable timeline component for react apps with additional dependencies written in Typescript.
See the Live Demo
Installation
npm install react-timeline --save Peer Dependencies
| Dependency | Version |
|---|---|
| React | ^17.0.2 |
| Styled Components | ^5.3.3 |
Example Usage
import Timeline, {
TimelineTheme,
TimelineProps,
ITimelineEvent
}
from 'react-timeline';
interface Props {
events: ITimelineEvent[]
}
// Optionally customize the default theme,
// or define your own
const theme = {
...TimelineTheme.default,
card: {
...TimelineTheme.default.card,
colors: {
text: '#5F646A',
background: '#FFFFFF',
active: {
border: '#3498CC',
background: '#FFFFFF',
text: '#5F646A',
}
},
}
};
const MyComponent = ({ events }: ): JSX.Element => (
<Timeline
events={events}
height={600}
showHeader
showDetailPanel
theme={theme}
/>,
); Notable Features
- Highly customizable to fit different design systems
- Lazy loads event content with content cache for optimal performance
- Render timelines with custom icons
- Support for date ranges, including 'Present'
- Implements sleek skeleton loading animations
- Supports either controlled and uncontrolled implementations
API Reference
Timeline
The props provided to the <Timeline /> component
| Parameter | Type | Description |
|---|---|---|
isLoading | boolean | Displays the loading indicator when set to true |
events | ITimelineEvent[] | The events to render. See definition below. |
activeEventId? | string | set which event is active (for controlled timeline). Defaults to the first event in the events array |
height | number | The overall height of the timeline, in pixels |
width | number | The overal width of the timeline, in pixels. (Note: this is overriden for responsive layouts |
icon | ReactNode | An optional react component to override the default timeline point icon |
title? | string | The title text, if rendering the header |
showHeader? | boolean | Displays the title header, when set to true |
showDetailPanel? | boolean | Renders the event detail panel; |
display | 'normal', 'condensed | Sets the layout type for the timeline. Defaults to normal |
customDateRenderer? | (date: DateRange ) => string | Optional function which overrides the default date render |
onClick? | (id: string) => void | Fired when a timeline event is clicked |
onMouseEnter? | (id: string) => void | 'Fired when the mouse enters the bounds of a timeline event |
onMouseLeave? | (id: string) => void | 'Fired when the mouse leaves the bounds of a timeline event |
ITimelineEvent
This is the type for the events provided to the Timeline for render
| Parameter | Type | Description |
|---|---|---|
id | string | The event id |
title | string | The event title |
date | Date or DateRange | The date or date range for the events |
description? | string | The event description |
active | boolean | Whether or not the event is active |
icon? | ReactNode | A custom icon, specific to the individual event |
content? | () => Promise<React.ReactNode> | An asyncronous function which returns the details for the event (for rendering in the detail panel) |
Notes:
Working with dates and date ranges
React timeline supports both singular dates (as Javascript Date instances) or with a DateRange:
type DateRange = {
start: Date;
end: Date | 'present';
}; To customize the way dates are rendered in the timeline, you need to provide a a customDateRenderer to the Timeline component. The function must accept either a Date or a Date range, depending on which date types you are implementing.
Here's an example implementation:
const renderDate = (date: Date | DateRange): string => {
if (date instanceof Date) {
return date.toLocaleString();
} else {
let start = date.start.toLocaleDateString();
let end;
if (date.end === 'present') {
end = 'Present';
} else {
end = date.end.toLocaleDateString();
}
return `${start} - ${end}`;
}
};