Overview
TimelineBlock displays chronological events in a vertical timeline with icons, descriptions, and tags. Features include search across all events, event type filtering, Load More pagination, past/upcoming separation, and density modes.
Key Features
Display
- Vertical timeline with colored icon circles
- Date range grouping (Today, Yesterday, Last 7 Days)
- Configurable event types with icons and colors
Search & Filter
- Search across event titles and descriptions
- Multi-select event type filtering
- Persisted filter state in localStorage
Pagination
- Load More pagination for large datasets
- Upcoming/past event separation (admin only)
- Configurable initial load and increment counts
Customization
- Default and compact density modes
- Custom card and expanded content rendering
- Built-in loading skeleton and empty states
When to Use TimelineBlock
- Displaying project or program activity history
- Showing scheduled events with upcoming/past separation
- Creating audit logs with searchable, filterable events
Live Examples
Simple Timeline
Basic timeline with a few events. Minimal configuration with event types and items only.
Project Alpha Created
New mobile app testing project initiated
Onboarding Survey
Initial participant survey created
50 Participants Reached
Project reached first recruitment milestone
Search & Filter
Enable search to find events by title/description, and multi-select filter by event type.
Project Beta Launched
Hardware testing program initiated
Feature Feedback Survey
Collecting feedback on new dashboard features
Bug Reporting Task
Participants asked to report UI bugs
Version 2.0 Released
Major update deployed to all testers
Weekly Insights Published
AI-generated summary of participant feedback
API Documentation Updated
New endpoints documented for v2.0
Density Modes
Toggle between default and compact layouts. Density preference persists via localStorage.
Project Beta Launched
Hardware testing program initiated
Feature Feedback Survey
Collecting feedback on new dashboard features
Bug Reporting Task
Participants asked to report UI bugs
Version 2.0 Released
Major update deployed to all testers
Weekly Insights Published
AI-generated summary of participant feedback
API Documentation Updated
New endpoints documented for v2.0
Upcoming Events
Show scheduled future events in a collapsible section (admin feature). Events with isUpcoming: true appear here.
Scheduled: Weekly Survey
Weekly feedback survey for all participants
Scheduled: Usability Test
Live usability testing session
Scheduled: Reminder Email
Reminder to complete pending activities
Project Started
Kicked off the Q4 testing initiative
Team Assembled
All 25 participants confirmed
Pagination (Load More)
Handle large datasets with progressive loading. Configure initial count and increment.
Feature Request Submitted #1
Activity from 1 days ago
Bug Report Filed #2
Activity from 1 days ago
Survey Completed #3
Activity from 1 days ago
Milestone Reached #4
Activity from 2 days ago
Document Updated #5
Activity from 2 days ago
Loading State
Built-in skeleton animation while data loads. Configurable number of skeleton items.
Project Alpha Created
New mobile app testing project initiated
Onboarding Survey
Initial participant survey created
50 Participants Reached
Project reached first recruitment milestone
Empty State
Custom messaging when no events exist. Configure icon, title, and description.
No activity yet
Events will appear here as they happen in your project.
Custom Rendering
Override default card content with custom rendering for specialized timeline displays.
Project Alpha Created
New mobile app testing project initiated
Onboarding Survey
Initial participant survey created
50 Participants Reached
Project reached first recruitment milestone
Props Reference
Core Props
Required props and event handlers for TimelineBlock.
| Prop | Type | Default | Description |
|---|---|---|---|
items | TimelineItem[] | required | Array of timeline events to display |
eventTypes | TimelineEventType[] | required | Event type definitions with icon, color, and label |
onEventClick | (item: T) => void | - | Callback when an event card is clicked |
onAdminAction | (item, action) => void | - | Callback for admin actions (edit, duplicate, delete) |
Feature Toggles
Boolean props to enable optional features.
| Prop | Type | Default | Description |
|---|---|---|---|
enableSearch | boolean | true | Enable search input for filtering events |
enableFiltering | boolean | true | Enable event type multi-select filter |
showUpcoming | boolean | false | Show upcoming events section (admin feature) |
showDensityToggle | boolean | true | Show density toggle (default/compact) |
Pagination & Loading
Props for controlling Load More pagination and loading states.
| Prop | Type | Default | Description |
|---|---|---|---|
initialLoadCount | number | 30 | Number of events to show initially |
loadMoreCount | number | 30 | Number of events to load on each 'Load More' click |
isLoading | boolean | false | Show loading skeleton state |
loadingCount | number | 5 | Number of skeleton items when loading |
Density & State
Props for controlling density modes and localStorage persistence.
| Prop | Type | Default | Description |
|---|---|---|---|
density | 'default' | 'compact' | 'default' | Current density mode ('default' or 'compact') |
densityStorageKey | string | - | localStorage key for persisting density preference |
Empty State
Props for customizing the empty state appearance.
| Prop | Type | Default | Description |
|---|---|---|---|
emptyIcon | IconDefinition | faCalendar | Icon shown in empty state |
emptyTitle | string | 'No events found' | Title text for empty state |
emptyDescription | string | 'There are no...' | Description text for empty state |
renderCard | (item: T) => ReactNode | - | Custom render function for card content |
Usage Patterns
import { TimelineBlock, TimelineItem, TimelineEventType } from '@/ui/blocks';
import { PageHeader } from '@/ui/components';
import { faFolderOpen, faClipboardList } from '@fortawesome/sharp-duotone-light-svg-icons';
const eventTypes: TimelineEventType[] = [
{ key: 'project', label: 'Project', icon: faFolderOpen, color: 'text-blue-400' },
{ key: 'survey', label: 'Survey', icon: faClipboardList, color: 'text-green-400' },
];
const events: TimelineItem[] = [
{ id: '1', type: 'project', title: 'Project Created', date: new Date() },
{ id: '2', type: 'survey', title: 'Survey Sent', date: new Date() },
];
<PageHeader title="Timeline" />
<TimelineBlock items={events} eventTypes={eventTypes} />