HopList - React Horizontal Timeline Component

A beautiful and customizable React horizontal timeline component with minimal parameters. Perfect for displaying progress steps, journey milestones, or any sequential data.

Demo & Playground

• 🌐 Live Demo: hoplist.akashghosh.xyz
• 🎮 Playground: CodeSandbox

Features

• 🎨 Fully Customizable Colors - Customize timeline and icon colors.
• 🔧 Custom Icons - Replace default icons with your own React components or SVGs.
• 📱 Responsive & Scrollable - A horizontally scrollable timeline that works on all screen sizes.
• ⚡ Lightweight - Minimal dependencies and optimized performance.
• 🎯 TypeScript Ready - Built with TypeScript support in mind.

Installation

npm install hoplist

Usage

Basic Usage

import React from 'react';
import HopList from 'hoplist';

const MyComponent = () => {
  const hops = [
    { hopTime: 1699123200, name: "Project Started" },
    { hopTime: 1699209600, name: "Requirements Gathered" },
    { hopTime: 1699296000, name: "Development Phase" },
    { hopTime: 1699382400, name: "Testing Phase" },
    { hopTime: 1699468800, name: "Project Completed" }
  ];

  return <HopList hops={hops} />;
};

export default MyComponent;

Advanced Usage with Customization

import React from 'react';
import HopList from 'hoplist';
import { PlayArrow, CheckCircle, Settings } from '@mui/icons-material'; // Example using Material-UI

const MyComponent = () => {
  const hops = [
    { hopTime: "2023-11-04T12:00:00Z", name: "Project Started" },
    { hopTime: "2023-11-05T12:00:00Z", name: "Requirements Gathered" },
    { hopTime: "2023-11-06T12:00:00Z", name: "Development Phase" },
    { hopTime: "2023-11-07T12:00:00Z", name: "Testing Phase" },
    { hopTime: "2023-11-08T12:00:00Z", name: "Project Completed" }
  ];

  return (
    <HopList 
      hops={hops}
      startIconColor="#4CAF50"
      timelineColor="#2196F3"
      stepIconColor="#FF9800"
      endIconColor="#9C27B0"
      startIcon={PlayArrow}
      endIcon={CheckCircle}
      stepIcon={Settings}
    />
  );
};

export default MyComponent;

Props

Prop	Type	Default	Description
hops	`Array<{hopTime: number	string, name: string}>`	Required
startIconColor	string	"#6B7280"	Color for the start icon border.
timelineColor	string	"#6B7280"	Color for the timeline lines.
stepIconColor	string	"#6B7280"	Color for the step icon borders.
endIconColor	string	"#6B7280"	Color for the end icon border.
startIcon	React.Component	Default SVG	React component for the start icon.
endIcon	React.Component	Default SVG	React component for the end icon.
stepIcon	React.Component	Default SVG	React component for intermediate step icons.

Data Structure

Hops Format

The hops prop expects a flat array of objects, where each object represents a single event on the timeline:

const hops = [
  { 
    hopTime: 1699123200,      // Unix timestamp or ISO Date String
    name: "Event Name"        // Display name for the event
  },
  { 
    hopTime: "2023-11-05T12:00:00Z",
    name: "Another Event"
  },
  // ... more events
];

Event Object Properties

Property	Type	Description
hopTime	number | string	Unix timestamp (in seconds) or a date string parsable by new Date().
name	string	Display name that will be shown below the timeline icon.

Example with Real Data

const projectTimeline = [
  { hopTime: 1699123200, name: "Kickoff Meeting" },
  { hopTime: 1699209600, name: "Requirements Analysis" },
  { hopTime: 1699296000, name: "Design Phase" },
  { hopTime: 1699382400, name: "Development Start" },
  { hopTime: 1699468800, name: "Feature Complete" },
  { hopTime: 1699555200, name: "Code Review" },
  { hopTime: 1699641600, name: "Testing" },
  { hopTime: 1699728000, name: "Bug Fixes" },
  { hopTime: 1699814400, name: "Production Deploy" }
];

Styling

The component can be styled by:

1. Using the color props (recommended):

   <HopList 
     hops={data}
     timelineColor="#your-color"
     // ... other color props
   />

2. Overriding CSS classes:

   .hoplist-container {
     /* Your custom styles for the main container */
   }
   
   .hoplist-timeline-line {
     /* Custom timeline styling */
   }

CSS Classes Available for Customization

• .hoplist-container - The main container that centers the component.
• .hoplist-scroll-container - The wrapper that handles horizontal scrolling.
• .hoplist-timeline - The flex container for all timeline items.
• .hoplist-item - An individual timeline item, including the icon and text.
• .hoplist-timeline-elements - A wrapper for the icon and connecting line.
• .hoplist-timeline-line - The connecting line between icons.
• .hoplist-icon - General class for all icons.
• .hoplist-start-icon - Specific class for the start icon.
• .hoplist-step-icon - Specific class for the step icons.
• .hoplist-end-icon - Specific class for the end icon.
• .hoplist-name - The event name text.
• .hoplist-timestamp - The timestamp text.

Time Format

The component automatically formats the hopTime value using the built-in timestampToDate function, which produces a readable format: YYYY-MM-DD HH:MM:SS.

If you need a different time format, you can modify the datetime-formatters.js file.

Dependencies

• React 16.8+ (for hooks support)

Browser Support

• Chrome 60+
• Firefox 60+
• Safari 12+
• Edge 79+

Contributing

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add some amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

License

This project is licensed under the MIT License.

---

Made with ❤️ for the React community