JSPM

smileytech-timeline

1.0.3
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 2
  • Score
    100M100P100Q30283F
  • License MIT

A beautiful, responsive timeline component for React applications with glassmorphism design, advanced filtering, and complete customization options

Package Exports

  • smileytech-timeline
  • smileytech-timeline/dist/index.esm.js
  • smileytech-timeline/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (smileytech-timeline) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@smileytech/timeline

A beautiful, responsive timeline component for React applications with glassmorphism design, advanced filtering capabilities, and complete customization options.

Timeline Demo

Features

  • 🎨 Beautiful Design: Glassmorphism UI with smooth animations and gradients
  • 📱 Responsive: Works perfectly on mobile, tablet, and desktop
  • 🔍 Advanced Filtering: Filter by categories with custom filter designs
  • 📊 Sorting: Sort events by date (newest/oldest first) with custom sort toggles
  • 📝 Markdown Support: Rich text descriptions with React Markdown
  • 🏢 Company Integration: Display company logos and information
  • 💻 Project Showcase: Showcase projects with tech stack and links
  • Performance: Optimized with intersection observer for smooth scroll-to-reveal animations
  • 🎯 TypeScript: Fully typed with comprehensive TypeScript support
  • 🎨 Complete Customization: Custom indicators, filters, toggles, and cards
  • 🔧 Generic Types: Use your own data structures with full TypeScript support
  • 📅 Flexible Date Display: Control date format (year, year-month, year-month-day, year-month-day-time)
  • 🎭 Custom Controls: Custom show/hide all toggles and sort toggles

Installation

npm install @smileytech/timeline

🚀 Live Demo

Try it out now! We've created a comprehensive demo application that showcases all the features of the timeline component.

Quick Start Demo

cd demo
npm install
npm run dev

Then visit http://localhost:3001 to see the timeline in action!

Demo Features

The demo includes 5 different examples:

  • 🎨 Default Timeline - Built-in glassmorphism design with filtering and sorting
  • 🎨 Custom Design - Hexagonal indicators and filters with custom styling
  • 📝 Markdown Support - Rich text content rendering with full markdown support
  • 🔧 Generic Types - Custom data structures with TypeScript generics
  • Minimal Example - Simple timeline without extra features

What You'll See

The demo showcases:

  • Glassmorphism UI with smooth animations and gradients
  • Responsive design that works on all devices
  • Advanced filtering by categories with custom filter designs
  • Date sorting with custom sort toggles
  • Markdown rendering for rich content
  • Company integration with logos and information
  • Project showcase with tech stacks and links
  • Custom indicators and controls
  • TypeScript support with generic types

Perfect for portfolios, resumes, and project timelines!

Quick Start

import { TimelineSection, TimelineEvent } from '@smileytech/timeline';
import '@smileytech/timeline/dist/timeline.css';

const events: TimelineEvent[] = [
  {
    id: '1',
    title: 'Senior Developer',
    description: 'Led development of multiple React applications...',
    category: 'work',
    date: new Date('2023-01-01'),
    company: {
      id: '1',
      name: 'Tech Company',
      logo_url: 'https://example.com/logo.png',
      website_url: 'https://example.com'
    },
    tech_stack_summary: ['React', 'TypeScript', 'Node.js']
  }
];

function App() {
  return (
    <TimelineSection 
      events={events}
      headerTitle="My Career Journey"
      headerSubtitle="A timeline of my professional and educational milestones"
    />
  );
}

API Reference

Components

Component Description Props
TimelineSection Main wrapper component with background and header TimelineSectionProps
Timeline Core timeline component with filtering and sorting TimelineProps
TimelineEvent Individual timeline event card TimelineEventProps

TimelineSection Props

Prop Type Default Required Description
events T[] - Array of timeline events
headerTitle string - Title displayed in the header
headerSubtitle string - Subtitle displayed in the header
showSectionBackground boolean true Whether to show the section background
showHeader boolean true Whether to show the header
showFilters boolean true Whether to show category filters
showSort boolean true Whether to show sort controls
isLoading boolean false Loading state
dateFormat DateFormat 'year-month' Date display format in indicators
renderEvent (event: T, index: number) => ReactNode - Custom render function for timeline cards
renderIndicator (event: T, index: number) => ReactNode - Custom render function for timeline indicators
renderFilter (category: string, isActive: boolean, onClick: () => void) => ReactNode - Custom render function for filter buttons
renderShowAllToggle (isAllActive: boolean, onClick: () => void) => ReactNode - Custom render function for show/hide all toggle
renderSortToggle (sortOrder: 'asc' | 'desc', onClick: () => void) => ReactNode - Custom render function for sort toggle
getEventDate (event: T) => Date | string - Override which property to use for date display
categories string[] - Explicit list of categories to show in filters

Timeline Props

Prop Type Default Required Description
events T[] - Array of timeline events
showFilters boolean true Whether to show category filters
showSort boolean true Whether to show sort controls
sortOrder 'asc' | 'desc' 'desc' Initial sort order
dateFormat DateFormat 'year-month' Date display format in indicators
isLoading boolean false Loading state
onSortChange (order: 'asc' | 'desc') => void - Callback when sort order changes
onFilterChange (filters: string[]) => void - Callback when filters change
renderEvent (event: T, index: number) => ReactNode - Custom render function for timeline cards
renderIndicator (event: T, index: number) => ReactNode - Custom render function for timeline indicators
renderFilter (category: string, isActive: boolean, onClick: () => void) => ReactNode - Custom render function for filter buttons
renderShowAllToggle (isAllActive: boolean, onClick: () => void) => ReactNode - Custom render function for show/hide all toggle
renderSortToggle (sortOrder: 'asc' | 'desc', onClick: () => void) => ReactNode - Custom render function for sort toggle
getEventDate (event: T) => Date | string - Override which property to use for date display
categories string[] - Explicit list of categories to show in filters

TimelineEvent Props

Prop Type Default Required Description
event T - Timeline event data
index number - Index of the event in the timeline
renderIndicator (event: T, index: number) => ReactNode - Custom render function for timeline indicators

Types

BaseTimelineEvent

Property Type Required Description
id string Unique identifier for the event
title string Title of the event
category string Category for filtering (e.g., 'work', 'education')
date Date | string Date of the event

TimelineEvent

Property Type Required Description
id string Unique identifier for the event
title string Title of the event
description string Description of the event (supports markdown)
category string Category for filtering
date Date | string Date of the event
company Company Company information
tech_stack_summary string[] Array of technologies used
projects Project[] Array of related projects

Company

Property Type Required Description
id string Unique identifier for the company
name string Company name
logo_url string URL to company logo
website_url string URL to company website

Project

Property Type Required Description
id string Unique identifier for the project
title string Project title
description string Project description
start_date string Project start date
end_date string Project end date
live_url string URL to live project
techStack string[] Array of technologies used
links ProjectLink[] Array of project links

DateFormat

Value Description Example
'year' Year only 2023
'year-month' Year and month 2023, Jan
'year-month-day' Full date 2023, Jan 15
'year-month-day-time' Date with time 2023, Jan 15, 2:30 PM

FilterState

Property Type Description
activeFilters string[] Array of currently active filter categories
isAllActive boolean Whether all categories are currently shown

Examples

💡 Want to see more examples? Check out our comprehensive demo with 5 different implementations!

Basic Usage

import { TimelineSection, TimelineEvent } from '@smileytech/timeline';
import '@smileytech/timeline/dist/timeline.css';

const events: TimelineEvent[] = [
  {
    id: '1',
    title: 'Senior Developer',
    description: 'Led development of multiple React applications...',
    category: 'work',
    date: new Date('2023-01-01'),
    company: {
      id: '1',
      name: 'Tech Company',
      logo_url: 'https://example.com/logo.png'
    },
    tech_stack_summary: ['React', 'TypeScript', 'Node.js']
  }
];

function App() {
  return (
    <TimelineSection 
      events={events}
      headerTitle="My Career Journey"
      headerSubtitle="A timeline of my professional and educational milestones"
    />
  );
}

Custom Render Functions

// Custom timeline card
const CustomCard = ({ event, index }) => (
  <div className="my-custom-card">
    <h3>{event.title}</h3>
    <p>{event.description}</p>
  </div>
);

// Custom indicator
const CustomIndicator = ({ event, index }) => (
  <div className="custom-indicator">
    <span></span>
  </div>
);

// Custom filter
const CustomFilter = ({ category, isActive, onClick }) => (
  <button 
    onClick={onClick}
    className={`custom-filter ${isActive ? 'active' : ''}`}
  >
    {category}
  </button>
);

<TimelineSection
  events={events}
  renderEvent={(event, index) => <CustomCard event={event} index={index} />}
  renderIndicator={(event, index) => <CustomIndicator event={event} index={index} />}
  renderFilter={(category, isActive, onClick) => (
    <CustomFilter category={category} isActive={isActive} onClick={onClick} />
  )}
/>

Generic Types with Custom Data

import { TimelineSection } from '@smileytech/timeline';

// Define your custom data type
interface CustomEvent {
  id: string;
  title: string;
  description: string;
  category: 'personal' | 'professional' | 'academic';
  date: Date;
  location: string;
  tags: string[];
}

const customEvents: CustomEvent[] = [
  {
    id: '1',
    title: 'Graduated from University',
    description: 'Completed my degree in Computer Science.',
    category: 'academic',
    date: new Date('2020-05-15'),
    location: 'University of Technology',
    tags: ['Computer Science', 'Graduation']
  }
];

// Custom render function
const CustomCard = ({ event, index }) => (
  <div className="my-custom-card">
    <h3>{event.title}</h3>
    <p>{event.description}</p>
    <span>{event.location}</span>
  </div>
);

<TimelineSection<CustomEvent>
  events={customEvents}
  renderEvent={(event, index) => <CustomCard event={event} index={index} />}
/>

Advanced Customization

// Hexagonal filter design
const CustomHexagonalFilter = ({ category, isActive, onClick }) => (
  <button onClick={onClick} className={`hexagon-filter ${isActive ? 'active' : ''}`}>
    <span>{category}</span>
  </button>
);

// Hexagonal indicator
const CustomHexagonalIndicator = ({ event, index }) => (
  <div className="hexagon-indicator">
    <span></span>
  </div>
);

<TimelineSection
  events={events}
  renderEvent={(event, index) => <CustomCard event={event} index={index} />}
  renderIndicator={(event, index) => <CustomHexagonalIndicator event={event} index={index} />}
  renderFilter={(category, isActive, onClick) => (
    <CustomHexagonalFilter category={category} isActive={isActive} onClick={onClick} />
  )}
  renderShowAllToggle={(isAllActive, onClick) => (
    <CustomHexagonalShowAll isAllActive={isAllActive} onClick={onClick} />
  )}
  renderSortToggle={(sortOrder, onClick) => (
    <CustomHexagonalSort sortOrder={sortOrder} onClick={onClick} />
  )}
  dateFormat="year"
/>

Different Date Formats

// Year only
<TimelineSection events={events} dateFormat="year" />

// Year and month
<TimelineSection events={events} dateFormat="year-month" />

// Full date
<TimelineSection events={events} dateFormat="year-month-day" />

// Date with time
<TimelineSection events={events} dateFormat="year-month-day-time" />

Custom Date Property

const events = [
  {
    id: '1',
    title: 'Birthday',
    category: 'personal',
    date: new Date('1990-08-20'),
    bday: '1990-08-20' // Custom date field
  }
];

<TimelineSection
  events={events}
  getEventDate={(event) => event.bday}
  dateFormat="year-month-day"
/>

Styling

The component includes its own CSS file with all necessary styles. Simply import the CSS:

import '@smileytech/timeline/dist/timeline.css';

No additional CSS framework required! The package is completely self-contained.

Browser Support

  • Chrome 88+
  • Firefox 87+
  • Safari 14+
  • Edge 88+

License

MIT

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

Support

For support, email support@smileytech.dev or create an issue in the repository.