Timeline

An animated vertical timeline with a scroll‑based progress indicator that presents chronological entries, each with a title, description, optional bullet points, and optional images. Ideal for company histories, product roadmaps, project milestones, changelogs, and “About Us” pages.

Use Cases

• Company history (founding story, key milestones, growth timeline)
• Product roadmap (past releases, upcoming features, version history)
• Project milestones (development phases, achievements, launches)
• Changelog/release notes (version updates, new features, fixes)
• About Us pages (team journey, company evolution)
• Career/resume pages (work history, education, achievements)
• Event timelines (conference schedule, wedding timeline)
• Process explanations (step‑by‑step workflows, onboarding steps)
• Case study timelines (project phases, results over time)

Properties

heading

Section heading displayed above the timeline. Type: string. Recommendations: length: 2‑5 words; style: Clear, descriptive – tells users what the timeline represents.

subheading

Supporting text below the heading. Provides context for the timeline. Type: string. Recommendations: length: 1‑2 sentences (15‑30 words); content: Explain what the timeline shows and why it matters.

entries

Array of timeline entries. Each entry represents a milestone/period with title, description, optional bullet points, and optional images. Type: array. Recommendations: count: 3‑6 entries for most timelines. More than 8 can feel overwhelming.; order: Chronological – either newest‑first (changelog) or oldest‑first (history); consistency: Keep similar detail level across entries. Don’t have one entry with 10 bullets and another with none.

lineColor

Color of the animated progress line. Use brand primary color or gradient colors. Type: string. Default: #3b82f6. Recommendations: brand: Use your brand’s primary color for consistency; contrast: Ensure good contrast against the background.

dotColor

Color of the timeline dots. Usually white or brand color. Type: string. Default: #ffffff.

customCss

Custom CSS styles for advanced styling. Type: string.

Best Practices

• Use 3‑6 entries for optimal visual balance (not too sparse, not overwhelming).
• Keep entry titles short: years (2024), dates (Q1 2024), or milestone names (Launch).
• Write descriptions in 1‑3 sentences per entry – concise but informative.
• Use bullet points for lists of achievements/features (one per line in bulletPoints).
• Add images only when they add value – not every entry needs images.
• Order entries chronologically (newest first OR oldest first – be consistent).
• Use search_unsplash for any images – don’t make up URLs.
• Match lineColor to your brand’s primary color for visual consistency.

Common Mistakes

Using too many entries (10+ entries)

Why it's a problem: Timeline becomes too long and loses impact. Users won’t scroll through endless entries.

Fix: Limit to 3‑6 key milestones. Group minor events or create separate timelines for different topics.

Inconsistent entry detail levels

Why it's a problem: Having one entry with 8 bullet points and images, and another with just a sentence, looks unbalanced.

Fix: Maintain consistent detail level. Either all entries have bullets/images, or keep it simple across all.

Using vague titles like ‘Milestone 1’, ‘Event 2’

Why it's a problem: Titles should be scannable and meaningful. Users often skim titles first.

Fix: Use specific titles: years (2024), quarters (Q3 2023), or descriptive names (Series A, Launch Day).

Not using search_unsplash for images

Why it's a problem: Made‑up image URLs result in broken images.

Fix: Call search_unsplash for each image with contextual queries. Use exact URLs returned.

Writing bullet points as a single long string

Why it's a problem: bulletPoints expects newline‑separated items. A single string shows as one bullet.

Fix: Use newlines to separate items: ‘Feature A\nFeature B\nFeature C’

Mixing chronological orders

Why it's a problem: Starting with 2020, then 2024, then 2022 is confusing.

Fix: Pick one order (newest‑first OR oldest‑first) and stick with it throughout.