Timeline-based portfolio with React and D3.js | Tutorial

This the complete code for the tutorial on how to build a responsive timeline-based portfolio with React, TypeScript, and D3.js.

Each subfolder in the src/lib/ directory represents a different section of the tutorial, the deployed demo is available here.

Feel free to clone/fork/refer to this repository, and build an awesome portfolio that represents you best!

Installing and running

This project is based on npm and vite and was built with Node.js v24.

To install the dependencies, from the root folder run:

npm install

To run the local dev server:

npm run dev

To build a production version:

npm run build

You can also run linting and formatting with npm run lint and npm run format, respectively.

Architecture

The project was scaffolded with the standard Vite project initializer and TypeScript template npm create . --template react-ts, uses Eslint and Prettier for code linting and formatting.

Core libraries

• D3.js - for calculating the layout positions, easings and interpolations
• sass-embedded - for using .scss modules; full counterpart of the sass package, but compatible with the recent versions of
• vite-plugin-sass-dts - a plugin for Vite that generates types for scss modules on the fly
• classnames - a library for dynamic styles
• react-use - a toolbox of React hooks; here used for measuring elements' dimensions.

Key modules and structure

Most of the code of interest is located in the src/lib/timeline folder. There is also a time-formatting function in the src/lib/utils

• src/lib/timeline/data - the sample data: a history of education, career milestones and projects
• src/lib/timeline/components - contains React Components TimelineMap and NodeCard.
  • src/lib/timeline/components/TimelineMap - "main" component for rendering the timeline. Takes the data as props, passes it to the engine for processing, and then renders the data over the x and y axes.
  • src/lib/timeline/components/NodeCard - takes the data for an item as props and renders it as a card.
• src/lib/timeline/engine - contains the core parts of the module that handle calculations for the month and year ticks, and the nodes' positions
  • src/lib/timeline/engine/constants.ts - shared constants
  • src/lib/timeline/engine/types.ts - shared types and interfaces
  • src/lib/timeline/engine/lanes.ts - logic for distributing the nodes over the lanes and avoiding collisions.
  • src/lib/timeline/engine/paths.ts - logic for drawing SVG paths to the nodes
  • src/lib/timeline/engine/index.ts - the TimelineEngine class, responsible for the calculations

src/App.tsx is the application's entry point, it imports the sample data, implements a placeholder handleOnNodeExpand method, and passes them as props to the TimelineMap component. (In a real-life project, the data would likely come from an AJAX call, or fetched in a server-side handler, e.g. in case of Next.js).

Sections and directories

• Initial setup and structure
• Data models and sample data
• Responsive timeline map
• Putting nodes on timeline
• Putting nodes on lanes
• Drawing lines to nodes
• Rich content cards
• Animating resize

Acknowledgements

The demo project uses free logos and pictures from Unsplash and UntitledUI in the sample data.