Timeline

A flexible and composable component for displaying chronological events in a vertical timeline. Supports icons, avatars, badges, user info, time display, grouping, hoverable/clickable items, collapsible sections, and manual composition.

---

Import

import { Timeline } from '@odyssee/components';
// Helpers: Timeline.Item, Timeline.Heading

---

Examples

Basic Timeline

Code Éditable

Résultat

---

Icon Variants

Code Éditable

Résultat

---

With User Information

Code Éditable

Résultat

---

Time Display

Code Éditable

Résultat

---

Grouped by Date

Code Éditable

Résultat

---

Hoverable and Clickable Items

Code Éditable

Résultat

---

Collapsible Timeline

Code Éditable

Résultat

---

Manual Composition

Code Éditable

Résultat

---

Props Table

Timeline Props

Prop	Type	Default	Description
items	Timeline.ItemData[]	—	Array of timeline items (data-driven).
grouped	boolean	false	Enable grouping by headings (e.g., date).
groups	Timeline.Group[]	—	Array of groups (each with heading and items).
showTime	boolean	false	Show time for each item.
timePosition	"left" | "right"	"left"	Position of time display.
hoverable	boolean	false	Make items hoverable/clickable.
collapsible	boolean	false	Enable collapsible timeline (show only recent items).
collapsedItemsCount	number	3	Number of items to show before collapsing.
collapseLabel	string	"Show older"	Label for collapse button.
lineColor	string	— (deprecated)	Line color (fixed in Preline).
dotColor	string	—	Dot color for timeline items.
children	JSX.Element | JSX.Element[]	—	Manual composition of timeline (Timeline.Item, Timeline.Heading).
className	string	—	Additional CSS classes.
id	string	auto-gen	HTML id attribute.
style	string	—	Inline styles.

Timeline.Item Props

Prop	Type	Default	Description
title	string | JSX.Element	— (required)	Title of the event.
description	string | JSX.Element	—	Description/details of the event.
icon	"dot" | "avatar" | "icon" | "badge"	"dot"	Icon type for the item.
iconContent	JSX.Element	—	Custom icon content (for "icon" type).
avatar	string	—	Avatar image URL (for "avatar" type).
initials	string	—	Initials for badge/avatar.
user	{ name: string; avatar?: string; initials?: string; onClick?: () => void }	—	User info to display below the item.
time	string	—	Time string to display.
showTime	boolean	—	Show time for this item.
timePosition	"left" | "right"	"left"	Position of time display for this item.
href	string	—	Link URL for clickable item.
onClick	() => void	—	Click handler for the item.
hoverable	boolean	false	Make this item hoverable/clickable.
isLast	boolean	false	Marks the last item (deprecated, use CSS selector).
lineColor	string	— (deprecated)	Line color (fixed in Preline).
dotColor	string	—	Dot color for this item.
className	string	—	Additional CSS classes.
id	string	auto-gen	HTML id attribute.
style	string	—	Inline styles.

Timeline.Heading Props

Prop	Type	Default	Description
children	string | JSX.Element	— (required)	Heading text or element.
className	string	—	Additional CSS classes.
id	string	auto-gen	HTML id attribute.
style	string	—	Inline styles.

---

Implementation Notes

• Variants:
  • "dot": Default small dot.
  • "avatar": User avatar image.
  • "badge": Initials in a badge.
  • "icon": Custom icon element.
• Grouping: Use grouped and groups for date or category grouping.
• Hoverable/Clickable: Use hoverable, href, and onClick for interactive items.
• Collapsible: Show only recent items, with a button to expand older events.
• Manual Composition: Use <Timeline>, <Timeline.Heading>, and <Timeline.Item> for full control.
• User Info: Display user name, avatar, or initials below the event.
• Time Display: Show time on left or right of each item.

---

Accessibility

• Timeline uses semantic <div>, <h3>, and <button>/<a> elements.
• Interactive items are keyboard-accessible and use ARIA roles as appropriate.
• Labels and descriptions should be clear for screen readers.
• Ensure color contrast for icons, dots, and text.

---

Best Practices

• Use Timeline for activity feeds, changelogs, project history, or event logs.
• Group items by date or category for clarity.
• Use avatars and badges for user attribution.
• Make items clickable for navigation or details.
• Use collapsible timelines for long histories.
• Prefer manual composition for complex layouts.

---

Related

• Pulse Framework
• Tailwind CSS Flex Utilities
• ARIA: Accessible Timelines

---