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.
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
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add some amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
Support
For support, email support@smileytech.dev or create an issue in the repository.