Timeline
NewA vertical event timeline with connecting lines, status-based styling, custom icons, and date labels. Supports default (left-aligned) and alternating layouts with full RTL support via logical properties.
Preview
Submitted
Application received and logged into the system
Document Verified
All required documents have been verified
Under Review
Your application is being reviewed by the team
Approved
Final approval pending
Installation
Usage
TypeScript
Examples
Basic Timeline
A simple timeline showing the progression of an application process with complete, current, and upcoming states.
Submitted
Application received and logged into the system
Document Verified
All required documents have been verified
Under Review
Your application is being reviewed by the team
Approved
Final approval pending
Activity Log
Use the icon slot to display user avatars. Accepts any React node including images and initials.
Sara commented on your pull request
"Looks good! Just one question about the error handling..."
Ahmed merged branch feature/auth
Pull request #47 was merged into main
Layla assigned you to issue #52
Fix pagination on the dashboard table
Omar deployed v2.4.1 to production
Alternating Layout
Events zigzag between left and right for a more visual presentation. Dates appear on the opposite side.
Project Kickoff
Requirements gathered, team assembled, and sprint planning completed
Alpha Release
Core features implemented and internal testing started
Beta Testing
Public beta with 500 users, collecting feedback and fixing issues
Public Launch
Production release with marketing campaign
Compact Mode
Smaller nodes and tighter spacing for inline use within cards or sidebars.
Order Placed
Order #1234 confirmed
Shipped
Package is on its way
Out for Delivery
Expected by end of day
Delivered
Support Ticket History
Timeline also works well with detailed content. Use the description for longer text and full context, with avatars to show who is involved.
Ticket opened by Fatima Al-Hassan
Unable to export reports in PDF format. The download starts but fails at 90% with a timeout error. Affects all report types on the dashboard. Browser: Chrome 120, OS: macOS Sonoma.
Assigned to Khalid — Priority: High
Investigating the PDF export service. Initial analysis shows the report generation exceeds the 30s timeout limit for large datasets. Checking server logs for the specific failure point.
Fix deployed — PR #389 merged
Increased timeout to 120s and added chunked processing for reports with 10k+ rows. Also added a progress indicator so users can see export status in real-time.
Confirmed fixed by Fatima
Tested with our largest report (15k rows) — exports in ~8 seconds now. The progress bar is a nice touch. Closing this ticket. Thank you!
Cards — Changelog
Use the cards prop to wrap each item's content in a card container. Great for changelogs, release notes, and content-rich timelines.
v2.5.0 — Dashboard Redesign
New analytics dashboard with real-time charts, customizable widgets, and dark mode support. Performance improved by 40% with virtualized lists.
v2.4.2 — Bug Fixes
Fixed PDF export timeout for large datasets. Resolved calendar date picker not respecting RTL layout in Safari.
v2.4.0 — Timeline Component
Introduced the Timeline component with default and alternating layouts, compact mode, card wrapping, and full RTL support.
v2.3.0 — Initial Release
First public release with 25 components, 5 themes, and bilingual support for English and Arabic.
Props
Timeline Props
| Name | Type | Default | Description |
|---|---|---|---|
itemsRequired | TimelineItem[] | — | Array of timeline event objects |
variant | 'default' | 'alternating' | 'default' | Layout variant: default (left-aligned) or alternating (zigzag) |
compact | boolean | false | Enable compact mode with smaller nodes and tighter spacing |
cards | boolean | false | Wrap each item's content in a card container |
className | string | — | Additional CSS classes |
TimelineItem Props
| Name | Type | Default | Description |
|---|---|---|---|
icon | React.ReactNode | — | Custom React node to display inside the timeline node |
titleRequired | string | — | Title text for the event |
titleAr | string | — | Arabic title (shown when direction is RTL) |
description | string | — | Description or details for the event |
descriptionAr | string | — | Arabic description |
date | string | — | Date or time label |
dateAr | string | — | Arabic date label |
statusRequired | 'complete' | 'current' | 'upcoming' | — | Status determines the visual style: complete (success), current (primary), or upcoming (muted) |
Accessibility
Semantic List Structure
The timeline renders as a list with role="list" and each item as role="listitem", providing a clear navigational structure for screen readers.
Aria Labels
The component includes an accessible aria-label that automatically switches between "Timeline" and the Arabic equivalent based on the current direction.
Decorative Icons Hidden
Timeline node icons are marked with aria-hidden="true" since the status information is conveyed through the text content, not the visual icon.
Status Through Content
The visual status (complete/current/upcoming) is reinforced through text styling changes, ensuring the information is not conveyed through color alone.
RTL Support
The Timeline component uses CSS logical properties throughout, so the layout automatically mirrors in RTL mode. No additional configuration is needed.
LTR (English)
Submitted
Application received and logged into the system
Document Verified
All required documents have been verified
Under Review
Your application is being reviewed by the team
Approved
Final approval pending
RTL (Arabic)
تم التقديم
تم استلام الطلب وتسجيله في النظام
تم التحقق من المستندات
تم التحقق من جميع المستندات المطلوبة
قيد المراجعة
يتم مراجعة طلبك من قبل الفريق
تمت الموافقة
في انتظار الموافقة النهائية
RTL Features
- •The connecting line and nodes flip to the right side in RTL
- •Content alignment mirrors automatically via logical properties
- •Alternating layout maintains proper left/right zigzag in both directions
- •Date labels can be localized via the dateAr prop
Best Practices
Do
- ✓ Use clear visual markers for each event status
- ✓ Show dates/times alongside event descriptions
- ✓ Support both vertical and horizontal layouts where appropriate
Don't
- ✗ Don't use for sequential steps — use Stepper instead
- ✗ Don't show too many events without pagination or scrolling
- ✗ Don't omit status indicators for events