Advanced Timeline Features

Ready to take your timeline to the next level? Learn how to handle hundreds of entries, group by time periods, and optimize performance.

See Examples Back to Basics

When Basic Timelines Aren't Enough

The Timeline component was designed for 4-8 major milestones, but what if you have 50? 100? What if you're using it like a blog with multiple entries per day? That's where these advanced features come in.

This page covers pagination, grouping, date formats, and performance considerations for timeline-heavy sites.

Compact Layout (Minimal)

October 2025

Polishing

I believe I have something solid. Ready for public view. I need to do some more polishing, but that is secondary. This is the MVP and there will surely be bugs and issues. But the most important part is to go to market.

October 2025

Development Starts

I've always been enamored by programming. I've dabbled in it several times. But with the help of AI, I can create things faster and better. So, I asked Claude (my favorite AI tool right now) to get started. I entered all my thoughts in a single chat—what I want, what i don't want, who this is for, and all other details I can think of. Once I have a working doc, I kept asking for edits like 'what about this' or 'consider this and that' until I got something that's 99% ready.

October 2025

Clear Path Forward

While cleaning up my kid's toys, I thought about the importance of simple and clear instructions. When I communicate to my son, I need to distill my words and remove fluff. Keep it simple or he'll just ignore me or misunderstand. That's the same thing for businesses. They need a clear roadmap ahead.

October 2025

Brainstorming

Later that evening, I went to work. I jotted down what I know (marketing) and listed down the problems I often see from my work. The biggest culprit—presence. With people's behaviors changing and moving more to online/digital transactions, local businesses need to have a presence online. They need to get found.

October 2025

The Idea Was Born

After countless hours of doomscrolling, I saw a reel about how the AI landscape is changing the way we approach work. It is enabling people and businesses who use it move faster and do things better. This made me think about what I know and can offer to other businesses.

Compact Layout

The compact layout removes visual decoration for a clean, dense display. Perfect for sidebars, widgets, or when you need to show many entries in minimal space.

<Timeline
  heading="Major Milestones"
  layout="compact"
/>

Pagination in Action (2 entries per page)

October 2025

Polishing

October 2025

Development Starts

What You're Seeing

The timeline above shows 2 entries per page (we have 4 total = 2 pages). Use the pagination controls below the timeline to navigate between pages. Notice:

Page 1 shows entries 1-2 (← button disabled, → button active)
Page 2 shows entries 3-4 (← button active, → button disabled)
Current page is highlighted in primary color
Fast performance - all pages pre-generated at build time (SSG)

<Timeline
  heading="Your Timeline Title"
  layout="vertical"
  paginateBy=2
  showPagination=true
  currentPage=1
/>

Pagination for Large Timelines

Got 100+ entries? Pagination keeps pages fast and prevents overwhelming visitors. Choose how many entries (or groups) to show per page, and the component generates navigation automatically.

Traditional Pagination

Show N entries per page with prev/next buttons and page numbers.

<Timeline
  heading="All Milestones"
  layout="vertical"
  paginateBy=10
  showPagination=true
  currentPage=1
/>

Shows 10 entries per page with pagination controls.

Paginate by Years

Group entries by year, then paginate years (show 5 years per page).

<Timeline
  heading="Our History"
  layout="vertical"
  groupBy="year"
  paginateBy=5
  showPagination=true
  currentPage=1
/>

Shows 5 years per page with year headers.

Paginate by Months

Group entries by month, then paginate months (show 3 months per page).

<Timeline
  heading="Monthly Activity"
  layout="compact"
  groupBy="month"
  paginateBy=3
  showPagination=true
  currentPage=1
/>

Shows 3 months per page with month headers.

Hidden Pagination (Developer Only)

Use pagination logic but hide controls from visitors (fixed subset).

<Timeline
  heading="Recent Milestones"
  layout="horizontal"
  paginateBy=10
  showPagination=
  currentPage=1
/>

Shows first 10 entries, no pagination UI.

Grouping Entries by Time Period

Grouping organizes entries under year or month headers, making long timelines scannable. Perfect when you have multiple entries per year or month.

Group by Year

<Timeline
  heading="Timeline"
  layout="vertical"
  groupBy="year"
/>

Entries grouped under year headers (2024, 2023, etc.).

Group by Month

<Timeline
  heading="Timeline"
  layout="vertical"
  groupBy="month"
/>

Entries grouped under month headers (January 2024, etc.).

Date Range Filter

<Timeline
  heading="2020s"
  layout="vertical"
  groupBy="dateRange"
  dateRange=[object Object]
/>

Show only entries from 2020-2029.

Date Display Formats

Control how dates appear on timeline cards. Set a default format for all entries, then override individual entries as needed.

Full Date

"January 15, 2024"

<Timeline
  heading="Timeline"
  layout="vertical"
  dateFormat="full"
/>

Best for: Daily entries, blog-style timelines

Month & Year

"January 2024" (default)

<Timeline
  heading="Timeline"
  layout="vertical"
  dateFormat="monthYear"
/>

Best for: Monthly milestones, general use

Year Only

"2024"

<Timeline
  heading="Timeline"
  layout="vertical"
  dateFormat="yearOnly"
/>

Best for: Yearly milestones, company history

Per-Entry Date Format Override

Set a default format on the Timeline component, then override specific entries in their frontmatter:

Component (default)

<Timeline
  heading="Our Story"
  layout="vertical"
  dateFormat="monthYear"
/>

Entry (override)

---
date: '2024-01-15'
title: 'Important Event'
description: 'Details...'
dateFormat: 'full'
---

Most entries show "January 2024" (component default), but this one shows "January 15, 2024" (entry override).

Handling Same-Day Entries

If you have multiple entries on the same date (e.g., March 15, 2024), the Timeline component uses enhanced sorting to keep them in a predictable order:

Primary sort: Date (newest first)
Secondary sort: `order` field (if both entries have it)
Tertiary sort: Filename (alphabetical)

Example: Same-Day Ordering

File: 2024-03-15-first.md

---
date: '2024-03-15'
title: 'Morning Event'
description: 'Happened first'
order: 1
---

File: 2024-03-15-second.md

---
date: '2024-03-15'
title: 'Evening Event'
description: 'Happened second'
order: 2
---

Both entries have the same date, but the `order` field ensures "Morning Event" appears before "Evening Event" in the timeline.

Performance Considerations

The Timeline component uses static site generation (SSG), which means all pages are built at compile time. Here's what you need to know about performance:

When to Use Pagination

Entries	Recommendation
1-20	No pagination needed. Use `limit` for teasers.
20-50	Optional pagination. Consider groupBy="year" for organization.
50-100	Use pagination or groupBy="year" with paginateBy=5.
100+	Always paginate. groupBy="month" with paginateBy=3 works well.

Build Time Impact

All timeline pages are generated at build time (not runtime)
More entries = longer build times, but zero runtime performance impact
Images are optimized during build (use OptimizedImage component)
Pagination creates multiple static pages (/timeline/page/2/, /timeline/page/3/, etc.)

Complete Field Reference

All available fields for timeline entries in src/content/timeline/:

---
# Required fields
date: '2024-01-15'          # ISO date (YYYY-MM-DD)
title: 'Milestone Title'    # 3-10 words recommended
description: 'Description of what happened and why it matters.'

# Optional fields
image: '/images/timeline/photo.jpg'  # Milestone image
imageAlt: 'Photo description'        # Alt text for accessibility
order: 1                              # Manual sort override (lower = first)
category: 'product'                   # For filtering (future feature)
featured: true                        # Highlight key milestones (future feature)
link: '/blog/detailed-post'           # Link to detailed page
dateFormat: 'full'                    # Per-entry date format override
---

Field Descriptions

date (required): ISO date string for sorting (YYYY-MM-DD format)
title (required): Milestone title/headline (keep concise: 3-10 words)
description (required): Milestone description (1-3 sentences recommended)
image (optional): Path to milestone image (store in public/images/timeline/)
imageAlt (optional): Alt text for image (WCAG compliance)
order (optional): Manual sort override for same-day entries (lower numbers first)
category (optional): Category tag for future filtering features
featured (optional): Flag to highlight key milestones (future feature)
link (optional): Link to detailed blog post or page about this milestone
dateFormat (optional): Per-entry override ('full', 'monthYear', 'yearOnly')

Advanced Features at a Glance

Pagination

Show entries in pages with visitor-facing controls or developer-configured limits.

Group by Year

Organize hundreds of entries by year with year headers and optional pagination.

Group by Month

Group entries by month for fine-grained organization of frequent milestones.

Date Range Filter

Show only entries within specific date ranges (e.g., "Our 2020s Timeline").

Date Formats

Choose full dates, month/year, or year-only display per entry or globally.

Performance

Handle hundreds of entries with smart pagination and static generation.

Ready to Build Your Advanced Timeline?

You now have all the tools to handle hundreds of timeline entries with smart organization and pagination. Start adding your milestones!

Back to Timeline Basics View All Components