|$ curl https://forge-ai.dev/api/markdown?path=docs/components/timeline
$cat docs/timeline.md
updated Recently·18 min read·published

Timeline

CSSHTMLTailwindBootstrapUIData DisplayIntermediate🎯Free Tools
Introduction

Timelines visualize chronological sequences of events. They work for project histories, user activity feeds, changelogs, onboarding steps, and process flows. This guide covers production-ready timeline patterns in plain HTML/CSS, Tailwind CSS, and Bootstrap — including vertical, horizontal, alternating, status-aware, nested, and rich-content layouts.

info

Use an ordered list (<ol>) for sequential events so screen readers announce position. Add aria-label to the timeline container to give screen readers extra context.
Vertical Timeline

A standard vertical timeline with a connecting line, dot indicators, and timestamps. Each item contains a title, description, and date. The connecting line uses a ::before pseudo-element on the container.

vertical-timeline
Live
untitled.html
HTML
1<div class="tl">
2 <div class="tl-item">
3 <div class="tl-dot">
4 </div>
5 <div class="tl-content">
6 <span class="tl-date">
7 Jan 15, 2025
8 </span>
9 <h4 class="tl-title">
10 Project Kickoff
11 </h4>
12 <p class="tl-desc">
13 Initial meeting with stakeholders to define scope,
14 timeline, and resource allocation for Q1 deliverables.
15 </p>
16 </div>
17 </div>
18 <div class="tl-item">
19 <div class="tl-dot">
20 </div>
21 <div class="tl-content">
22 <span class="tl-date">
23 Feb 3, 2025
24 </span>
25 <h4 class="tl-title">
26 Design Review
27 </h4>
28 <p class="tl-desc">
29 Finalized UI/UX mockups and component library.
30 Received approval from the design team and product owner.
31 </p>
32 </div>
33 </div>
34 <div class="tl-item">
35 <div class="tl-dot">
36 </div>
37 <div class="tl-content">
38 <span class="tl-date">
39 Feb 20, 2025
40 </span>
41 <h4 class="tl-title">
42 Sprint 1 Complete
43 </h4>
44 <p class="tl-desc">
45 Shipped authentication, dashboard layout, and
46 settings page. 14 story points delivered across 3 features.
47 </p>
48 </div>
49 </div>
50 <div class="tl-item">
51 <div class="tl-dot active">
52 </div>
53 <div class="tl-content">
54 <span class="tl-date">
55 Mar 8, 2025
56 </span>
57 <h4 class="tl-title">
58 Sprint 2 In Progress
59 </h4>
60 <p class="tl-desc">
61 Currently building the notification system, real-time
62 collaboration, and data export functionality.
63 </p>
64 </div>
65 </div>
66</div>
preview
Status Icons

Status-aware timeline nodes with colored icons — green check for completed, blue pulse for in-progress, yellow clock for pending, and red X for blocked. Visual status reduces cognitive load and communicates project health at a glance.

status-timeline
Live
untitled.html
HTML
1<div class="tl status-tl">
2 <div class="tl-item">
3 <div class="tl-icon done">
4 <svg width="12" height="12" viewBox="0 0 24 24" fill="none"
5 stroke="currentColor" stroke-width="3" stroke-linecap="round"
6 stroke-linejoin="round">
7 <polyline points="20 6 9 17 4 12"/>
8 </svg>
9 </div>
10 <div class="tl-content">
11 <span class="tl-date">
12 Jan 15, 2025
13 </span>
14 <h4 class="tl-title">
15 Requirements Gathering
16 </h4>
17 <p class="tl-desc">
18 Stakeholder interviews, user research, and
19 competitive analysis completed across 12 segments.
20 </p>
21 </div>
22 </div>
23 <div class="tl-item">
24 <div class="tl-icon done">
25 <svg width="12" height="12" viewBox="0 0 24 24" fill="none"
26 stroke="currentColor" stroke-width="3" stroke-linecap="round"
27 stroke-linejoin="round">
28 <polyline points="20 6 9 17 4 12"/>
29 </svg>
30 </div>
31 <div class="tl-content">
32 <span class="tl-date">
33 Feb 1, 2025
34 </span>
35 <h4 class="tl-title">
36 Architecture Design
37 </h4>
38 <p class="tl-desc">
39 System architecture, database schema, and
40 API contracts finalized and reviewed.
41 </p>
42 </div>
43 </div>
44 <div class="tl-item">
45 <div class="tl-icon progress">
46 <svg width="12" height="12" viewBox="0 0 24 24" fill="none"
47 stroke="currentColor" stroke-width="3" stroke-linecap="round"
48 stroke-linejoin="round">
49 <circle cx="12" cy="12" r="10"/>
50 </svg>
51 </div>
52 <div class="tl-content">
53 <span class="tl-date">
54 Mar 1, 2025
55 </span>
56 <h4 class="tl-title">
57 Development Sprint
58 </h4>
59 <p class="tl-desc">
60 Core features being built. Frontend and backend
61 teams working in parallel on separate tracks.
62 </p>
63 </div>
64 </div>
65 <div class="tl-item">
66 <div class="tl-icon pending">
67 <svg width="12" height="12" viewBox="0 0 24 24" fill="none"
68 stroke="currentColor" stroke-width="3" stroke-linecap="round"
69 stroke-linejoin="round">
70 <circle cx="12" cy="12" r="10"/>
71 <line x1="12" y1="8" x2="12" y2="12"/>
72 <line x1="12" y1="16" x2="12.01" y2="16"/>
73 </svg>
74 </div>
75 <div class="tl-content">
76 <span class="tl-date">
77 Apr 1, 2025
78 </span>
79 <h4 class="tl-title">
80 QA & Testing
81 </h4>
82 <p class="tl-desc">
83 Manual and automated testing, performance
84 benchmarking, and security audit scheduled.
85 </p>
86 </div>
87 </div>
88 <div class="tl-item">
89 <div class="tl-icon blocked">
90 <svg width="12" height="12" viewBox="0 0 24 24" fill="none"
91 stroke="currentColor" stroke-width="3" stroke-linecap="round"
92 stroke-linejoin="round">
93 <circle cx="12" cy="12" r="10"/>
94 <line x1="4.93" y1="4.93" x2="19.07" y2="19.07"/>
95 </svg>
96 </div>
97 <div class="tl-content">
98 <span class="tl-date">
99 May 1, 2025
100 </span>
101 <h4 class="tl-title">
102 Deployment
103 </h4>
104 <p class="tl-desc">
105 Staging deployment, UAT sign-off, and production
106 release pending environment configuration.
107 </p>
108 </div>
109 </div>
110</div>
preview
Alternating Layout

Items alternate between left and right sides of a central line. This layout works well for wide screens and provides a balanced visual rhythm. Each side has a card with its own date, title, and description.

alternating-timeline
Live
untitled.html
HTML
1<div class="alt-tl">
2 <div class="alt-item left">
3 <div class="alt-card">
4 <span class="tl-date">
5 Q1 2025
6 </span>
7 <h4 class="tl-title">
8 Research Phase
9 </h4>
10 <p class="tl-desc">
11 Market analysis, user interviews, and technical
12 feasibility studies across 12 customer segments.
13 </p>
14 </div>
15 </div>
16 <div class="alt-item right">
17 <div class="alt-card">
18 <span class="tl-date">
19 Q2 2025
20 </span>
21 <h4 class="tl-title">
22 Design Phase
23 </h4>
24 <p class="tl-desc">
25 Wireframes, prototypes, and design system creation.
26 Three design iterations with user testing.
27 </p>
28 </div>
29 </div>
30 <div class="alt-item left">
31 <div class="alt-card">
32 <span class="tl-date">
33 Q3 2025
34 </span>
35 <h4 class="tl-title">
36 Build Phase
37 </h4>
38 <p class="tl-desc">
39 Agile development with two-week sprints. 84 story
40 points delivered across 6 features in 4 sprints.
41 </p>
42 </div>
43 </div>
44 <div class="alt-item right">
45 <div class="alt-card">
46 <span class="tl-date">
47 Q4 2025
48 </span>
49 <h4 class="tl-title">
50 Launch Phase
51 </h4>
52 <p class="tl-desc">
53 Beta testing, performance optimization, documentation,
54 and zero-downtime production deployment.
55 </p>
56 </div>
57 </div>
58</div>
preview
Horizontal Timeline

A horizontally scrolling timeline for roadmaps, project milestones, and historical events. Uses CSS overflow-x for scrolling on narrow screens. Each milestone has a date, title, and brief status description.

horizontal-timeline
Live
untitled.html
HTML
1<div class="h-tl-wrap">
2 <div class="h-tl">
3 <div class="h-tl-item">
4 <div class="h-dot done">
5 </div>
6 <div class="h-card">
7 <span class="h-date">
8 Jan
9 </span>
10 <h4 class="h-title">
11 Planning
12 </h4>
13 <p class="h-desc">
14 Scope defined
15 </p>
16 </div>
17 </div>
18 <div class="h-tl-item">
19 <div class="h-dot done">
20 </div>
21 <div class="h-card">
22 <span class="h-date">
23 Feb
24 </span>
25 <h4 class="h-title">
26 Design
27 </h4>
28 <p class="h-desc">
29 Mockups ready
30 </p>
31 </div>
32 </div>
33 <div class="h-tl-item">
34 <div class="h-dot active">
35 </div>
36 <div class="h-card">
37 <span class="h-date">
38 Mar
39 </span>
40 <h4 class="h-title">
41 Development
42 </h4>
43 <p class="h-desc">
44 In progress
45 </p>
46 </div>
47 </div>
48 <div class="h-tl-item">
49 <div class="h-dot">
50 </div>
51 <div class="h-card">
52 <span class="h-date">
53 Apr
54 </span>
55 <h4 class="h-title">
56 Testing
57 </h4>
58 <p class="h-desc">
59 QA phase
60 </p>
61 </div>
62 </div>
63 <div class="h-tl-item">
64 <div class="h-dot">
65 </div>
66 <div class="h-card">
67 <span class="h-date">
68 May
69 </span>
70 <h4 class="h-title">
71 Launch
72 </h4>
73 <p class="h-desc">
74 Go live
75 </p>
76 </div>
77 </div>
78 </div>
79</div>
preview
Compact Activity Feed

A dense, compact timeline for activity feeds, audit logs, and changelogs. Each item is a single line with timestamp, colored icon, and action description. Icons indicate action type — additions, modifications, errors, and removals.

compact-activity
Live
untitled.html
HTML
1<div class="feed">
2 <div class="feed-item">
3 <span class="feed-time">
4 2m ago
5 </span>
6 <span class="feed-icon green">
7 +
8 </span>
9 <span class="feed-text">
10 <strong>
11 Sarah
12 </strong>
13 deployed
14 <code>
15 v2.4.1
16 </code>
17 to production
18 </span>
19 </div>
20 <div class="feed-item">
21 <span class="feed-time">
22 14m ago
23 </span>
24 <span class="feed-icon blue">
25
26 </span>
27 <span class="feed-text">
28 <strong>
29 Mike
30 </strong>
31 opened PR #847: Fix auth token refresh
32 </span>
33 </div>
34 <div class="feed-item">
35 <span class="feed-time">
36 32m ago
37 </span>
38 <span class="feed-icon yellow">
39 !
40 </span>
41 <span class="feed-text">
42 <strong>
43 CI
44 </strong>
45 build failed on
46 <code>
47 main
48 </code>
49 — lint errors
50 </span>
51 </div>
52 <div class="feed-item">
53 <span class="feed-time">
54 1h ago
55 </span>
56 <span class="feed-icon green">
57 +
58 </span>
59 <span class="feed-text">
60 <strong>
61 Alex
62 </strong>
63 merged PR #845: Add rate limiting middleware
64 </span>
65 </div>
66 <div class="feed-item">
67 <span class="feed-time">
68 2h ago
69 </span>
70 <span class="feed-icon purple">
71
72 </span>
73 <span class="feed-text">
74 <strong>
75 Jordan
76 </strong>
77 updated API docs for v2 endpoints
78 </span>
79 </div>
80 <div class="feed-item">
81 <span class="feed-time">
82 3h ago
83 </span>
84 <span class="feed-icon red">
85
86 </span>
87 <span class="feed-text">
88 <strong>
89 Bot
90 </strong>
91 auto-closed stale issue #623 (30d inactivity)
92 </span>
93 </div>
94 <div class="feed-item">
95 <span class="feed-time">
96 5h ago
97 </span>
98 <span class="feed-icon blue">
99
100 </span>
101 <span class="feed-text">
102 <strong>
103 Emily
104 </strong>
105 started review on PR #842: DB migration
106 </span>
107 </div>
108</div>
preview
Nested Events

Parent events can contain nested child events for sub-steps. This is useful for sprint retrospectives, release notes, or any hierarchical process where major milestones contain smaller tasks.

nested-timeline
Live
untitled.html
HTML
1<div class="tl nested-tl">
2 <div class="tl-item">
3 <div class="tl-dot active">
4 </div>
5 <div class="tl-content">
6 <span class="tl-date">
7 Sprint 12 — Mar 1 to Mar 14
8 </span>
9 <h4 class="tl-title">
10 Authentication Overhaul
11 </h4>
12 <p class="tl-desc">
13 Complete redesign of the auth system with OAuth 2.0 and SAML support.
14 </p>
15 <div class="tl-nested">
16 <div class="tl-nested-item">
17 <span class="tl-nested-dot done">
18 </span>
19 <span class="tl-nested-text">
20 Implement OAuth 2.0 provider abstraction
21 </span>
22 </div>
23 <div class="tl-nested-item">
24 <span class="tl-nested-dot done">
25 </span>
26 <span class="tl-nested-text">
27 Add SAML integration for enterprise SSO
28 </span>
29 </div>
30 <div class="tl-nested-item">
31 <span class="tl-nested-dot active">
32 </span>
33 <span class="tl-nested-text">
34 Build session management dashboard
35 </span>
36 </div>
37 <div class="tl-nested-item">
38 <span class="tl-nested-dot pending">
39 </span>
40 <span class="tl-nested-text">
41 Write migration script for existing users
42 </span>
43 </div>
44 </div>
45 </div>
46 </div>
47</div>
preview
Rich Content Cards

Timeline items as structured cards with tags, metadata, and action links. Useful for release notes, portfolio histories, or product update feeds.

rich-card-timeline
Live
untitled.html
HTML
1<div class="rich-tl">
2 <div class="rich-item">
3 <div class="rich-dot active">
4 </div>
5 <div class="rich-card">
6 <div class="rich-header">
7 <span class="rich-date">
8 Mar 15, 2025
9 </span>
10 <div class="rich-tags">
11 <span class="tag feature">
12 Feature
13 </span>
14 <span class="tag major">
15 Major
16 </span>
17 </div>
18 </div>
19 <h4 class="rich-title">
20 Release v2.0
21 </h4>
22 <p class="rich-desc">
23 Redesigned dashboard, new public API, and 40% faster page loads.
24 </p>
25 <a href="#" class="rich-link">
26 View changelog →
27 </a>
28 </div>
29 </div>
30 <div class="rich-item">
31 <div class="rich-dot">
32 </div>
33 <div class="rich-card">
34 <div class="rich-header">
35 <span class="rich-date">
36 Feb 20, 2025
37 </span>
38 <div class="rich-tags">
39 <span class="tag fix">
40 Fix
41 </span>
42 </div>
43 </div>
44 <h4 class="rich-title">
45 Hotfix v1.9.2
46 </h4>
47 <p class="rich-desc">
48 Resolved auth token refresh race condition and edge caching bug.
49 </p>
50 <a href="#" class="rich-link">
51 View details →
52 </a>
53 </div>
54 </div>
55 <div class="rich-item">
56 <div class="rich-dot">
57 </div>
58 <div class="rich-card">
59 <div class="rich-header">
60 <span class="rich-date">
61 Jan 10, 2025
62 </span>
63 <div class="rich-tags">
64 <span class="tag docs">
65 Docs
66 </span>
67 </div>
68 </div>
69 <h4 class="rich-title">
70 Docs Refresh
71 </h4>
72 <p class="rich-desc">
73 Rewrote onboarding guides and added interactive code previews.
74 </p>
75 <a href="#" class="rich-link">
76 Browse docs →
77 </a>
78 </div>
79 </div>
80</div>
preview
Grouped Milestones

Group related events under year or quarter headers. This pattern scales better for long histories — users can scan headers before diving into individual items.

grouped-milestones
Live
untitled.html
HTML
1<div class="group-tl">
2 <div class="group-year">
3 2025
4 </div>
5 <div class="group-list">
6 <div class="group-item">
7 <div class="group-dot active">
8 </div>
9 <div>
10 <span class="group-month">
11 Mar
12 </span>
13 <h4 class="group-title">
14 Series A Funding
15 </h4>
16 </div>
17 </div>
18 <div class="group-item">
19 <div class="group-dot">
20 </div>
21 <div>
22 <span class="group-month">
23 Jan
24 </span>
25 <h4 class="group-title">
26 Public Beta Launch
27 </h4>
28 </div>
29 </div>
30 </div>
31 <div class="group-year">
32 2024
33 </div>
34 <div class="group-list">
35 <div class="group-item">
36 <div class="group-dot">
37 </div>
38 <div>
39 <span class="group-month">
40 Oct
41 </span>
42 <h4 class="group-title">
43 Seed Round Closed
44 </h4>
45 </div>
46 </div>
47 <div class="group-item">
48 <div class="group-dot">
49 </div>
50 <div>
51 <span class="group-month">
52 Jun
53 </span>
54 <h4 class="group-title">
55 MVP Released
56 </h4>
57 </div>
58 </div>
59 <div class="group-item">
60 <div class="group-dot">
61 </div>
62 <div>
63 <span class="group-month">
64 Jan
65 </span>
66 <h4 class="group-title">
67 Company Founded
68 </h4>
69 </div>
70 </div>
71 </div>
72</div>
preview
HTML Structure

The vertical timeline uses a simple list structure with a pseudo-element line. Each item has a dot indicator and content block. The::before pseudo-element on the container draws the connecting line automatically — no extra DOM nodes needed.

timeline-structure.html
HTML
1<div class="timeline">
2 <div class="timeline-item">
3 <div class="timeline-dot"></div>
4 <div class="timeline-content">
5 <span class="timeline-date">Mar 8, 2025</span>
6 <h4 class="timeline-title">Event Title</h4>
7 <p class="timeline-desc">
8 Description of what happened at this point.
9 </p>
10 </div>
11 </div>
12 <div class="timeline-item">
13 <div class="timeline-dot active"></div>
14 <div class="timeline-content">
15 <span class="timeline-date">Mar 15, 2025</span>
16 <h4 class="timeline-title">Next Event</h4>
17 <p class="timeline-desc">More details here.</p>
18 </div>
19 </div>
20</div>

info

For vertical timelines, use ::before pseudo-elements on the container to draw the connecting line. This avoids extra DOM nodes and keeps the HTML clean. Set position: relative on items and use absolute positioning for dots and icons.

warning

Horizontal timelines require careful handling on mobile. Useoverflow-x: auto on the wrapper and setmin-width on the track to prevent items from collapsing. Add a subtle scroll hint or CSS scroll-snap for touch devices.
Accessibility

Timelines are visual by nature, so make sure the same information is available to assistive technologies. Treat a timeline as a structured list of events and communicate status with more than just color.

  • Use <ol> (or role="list") so screen readers announce item counts and positions.
  • Add an aria-label such as "Project history" to the timeline container.
  • Pair status colors with text labels or icons — never rely on color alone.
  • Ensure interactive cards or links are reachable by keyboard and show visible focus.
  • Use relative and absolute timestamps consistently; avoid mixing "2m ago" and "Mar 8, 2025" in the same timeline.
  • For horizontal scrolling timelines, expose the scrollable region to assistive tech with role="region" and an accessible name.
Best Practices
  • Use semantic HTML — consider <ol> for sequential events to convey ordering.
  • Always show timestamps in a consistent format (relative or absolute, not both).
  • For status timelines, use distinct colors and icons — don't rely on color alone.
  • Keep timeline items scannable: short titles, brief descriptions, and clear dates.
  • On narrow screens, switch from alternating to single-side layout.
  • Use aria-label on timeline containers for screen reader context.
  • For long timelines, implement virtual scrolling or pagination to maintain performance.

Community

Get help on Slack, Discord or VIP

Stuck on a guide? Join the community and ask.