Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesTo render a vertical timeline in React, install the npm package react-vertical-timeline-component, import its two components and its stylesheet, then nest one VerticalTimelineElement per entry inside a VerticalTimeline. The npm listing describes the package as “Vertical timeline for React.js.” The steps below cover installation, a minimal working timeline, the props you are most likely to customize, and the mistakes that most often leave a timeline unstyled or pointed at the wrong library.
Install the correct package
Install the package from npm. The name must match exactly, because a similarly named library, vertical-timeline-component-react, uses a different API and will not work with the code in this guide.
- Open a terminal in your React project’s root directory.
- Run
npm i react-vertical-timeline-component. - Confirm the package appears under
dependenciesinpackage.json.
The package’s npm package page is the primary reference for the current release, its README, and its license. Install the current version rather than pinning an old one unless you have a specific reason to; the version details are covered later in this guide.
Build a minimal timeline
The package exports two components. VerticalTimeline is the wrapper that lays out the line and its markers. VerticalTimelineElement is a single entry. The stylesheet is imported separately, and the import is required for the package’s supplied styling. The example below adapts the usage shown in the package’s documentation.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →#1 Best Overall
import {
VerticalTimeline,
VerticalTimelineElement,
} from 'react-vertical-timeline-component';
import 'react-vertical-timeline-component/style.min.css';
function Timeline() {
return (
<VerticalTimeline>
<VerticalTimelineElement date="2011 - present">
<h3 className="vertical-timeline-element-title">Creative Director</h3>
<h4 className="vertical-timeline-element-subtitle">Miami, FL</h4>
<p>Describe the event here.</p>
</VerticalTimelineElement>
</VerticalTimeline>
);
}
export default Timeline;Render <Timeline /> anywhere in your app. The date text, the heading and the paragraph are ordinary React children, so you can replace them with your own content.
Render multiple entries from data
Most real timelines are driven by an array. Map the array to VerticalTimelineElement and give each element a stable key:
const jobs = [
{ id: 1, date: '2019 - 2023', title: 'Frontend Engineer', place: 'Lisbon', text: 'Built the design system.' },
{ id: 2, date: '2023 - present', title: 'Lead Engineer', place: 'Remote', text: 'Led a component library rewrite.' },
];
function Timeline() {
return (
<VerticalTimeline>
{jobs.map((job) => (
<VerticalTimelineElement key={job.id} date={job.date}>
<h3 className="vertical-timeline-element-title">{job.title}</h3>
<h4 className="vertical-timeline-element-subtitle">{job.place}</h4>
<p>{job.text}</p>
</VerticalTimelineElement>
))}
</VerticalTimeline>
);
}The sample data above is illustrative only. Replace it with your own entries.
Customize position, colors and icons
The README documents the element properties below. Where the sources do not state a default, the table says so rather than guessing.
| Prop | What it controls | Documented default |
|---|---|---|
date |
Date text shown with the entry (the package example uses "2011 - present") |
Not stated |
position |
Which side of the line the entry sits on: left or right |
Not stated |
icon |
Element rendered inside the entry’s marker | Not stated |
style |
Inline style applied to the element’s wrapper | Not stated |
iconStyle |
Inline style for the marker, typically used for its colors | Not stated |
contentStyle |
Inline style for the content box | Not stated |
contentArrowStyle |
Inline style for the arrow connecting the marker to the content box | Not stated |
className hooks |
Class names for targeting parts of an entry, such as vertical-timeline-element-title and vertical-timeline-element-subtitle used in the example |
Not stated |
| Click handler | Runs when an entry is clicked; check the README for the exact prop name | Not stated |
visible |
Boolean that displays the element even when it is outside the viewport | false |
intersectionObserverProps |
Options passed to the viewport observer | { rootMargin: '0px 0px 40px 0px' } |
A typical customization looks like this:
<VerticalTimelineElement
date="2023 - present"
position="right"
icon={<span>1</span>}
iconStyle={{ background: '#1d4ed8', color: '#ffffff' }}
contentStyle={{ background: '#f8fafc' }}
contentArrowStyle={{ borderRight: '7px solid #f8fafc' }}
>
<h3 className="vertical-timeline-element-title">Lead Engineer</h3>
<p>Led a component library rewrite.</p>
</VerticalTimelineElement>The colors in that example are placeholders. The point is which prop controls which part of the entry: the marker takes iconStyle, the box takes contentStyle, and the connecting arrow takes contentArrowStyle.
Control visibility on scroll
The visible prop is a Boolean. According to the package README, it displays an element even when that element is outside the viewport, and its documented default is false. Leave the default in place unless the page needs something different.
The intersectionObserverProps option configures the observer that decides when an entry is in view. Its documented default is { rootMargin: '0px 0px 40px 0px' }, which extends the observed area by 40 pixels at the bottom. Change it only if the default viewport behavior does not suit your layout. The README is the reference for exactly how these options behave, so confirm the behavior in your own page rather than relying on this summary.
Troubleshooting
- The timeline renders with no styling. The stylesheet import is missing or the path is wrong. It must be exactly
react-vertical-timeline-component/style.min.css. Your bundler also needs to handle CSS imports, which most React setups do. - Titles and subtitles look different from the example. The example uses the
vertical-timeline-element-titleandvertical-timeline-element-subtitleclass names. Keep them if you want your markup to match the documented example. VerticalTimelineorVerticalTimelineElementis undefined or fails to render. Check the package name inpackage.json. Code written forvertical-timeline-component-react, which exportsTimeline,EventsandEvent, will not work with this package.- Entries outside the viewport do not appear as expected. Review the
visibleandintersectionObserverPropssettings described above.
Two similarly named packages
Search results surface both names, and they are easy to mix up. The distinction matters because the imports are different:
Recommended Free Tools
Best Value
react-vertical-timeline-componentexportsVerticalTimelineandVerticalTimelineElement, and this guide covers it.vertical-timeline-component-reacthas a different API built aroundTimeline,EventsandEvent. Use its own README for setup.
Version and license
The npm listing reports version 4.0.0 and an MIT license as of this writing. Newer releases may have been published since then, so check the npm page before writing version-specific instructions for your team. Some property descriptions in this guide come from an older README copy for version 3.5.1; the current README on npm is the authoritative reference for the props in your installed version.
Using the timeline in a Docusaurus page
A common follow-up question is whether this timeline can be placed inside a Docusaurus documentation page. The package’s documentation does not cover Docusaurus, so this is not an officially documented integration. Because the component is a standard React component, it can generally be imported into an MDX page, and the same import and stylesheet steps apply. Because the visibility behavior depends on the viewport, verify the result in both the development server and a production build before relying on it.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
