HorizontalTimeline Component

Overview

The HorizontalTimeline component is a versatile visual timeline that displays events along a horizontal axis. It provides an interactive way to visualize and navigate through time-based events, with support for different event states, sizes, and selections.

For timeline component styling customization and tenant-specific theming, see the Tenant Styling Implementation Guide.

Prerequisites

• UI.Razor library
• A data provider implementing ITimelineEventDataProvider
• CSS styles for timeline rendering

Installation/Setup

The HorizontalTimeline component is part of the UI.Razor library. To use it in your project:

1. Add a reference to the UI.Razor library:

   <ProjectReference Include="..\..\libs\UI.Razor\UI.Razor.csproj" />

2. Add the necessary using statements:

   @using UI.Razor.Components
   @using UI.Razor.Models

3. Implement or inject an ITimelineEventDataProvider:

   @inject ITimelineEventDataProvider TimelineDataProvider

Basic Usage

<HorizontalTimeline 
    TimelineEventDataProvider="TimelineDataProvider" 
    OnEventSelected="HandleEventSelected" 
    Options="_timelineOptions" />

@code {
    private TimelineOptions _timelineOptions = new()
    {
        TimestampFormat = "d MMM",
        MaxEventSize = 50
    };

    private async Task HandleEventSelected(TimelineEvent evt)
    {
        // Handle selection
    }
}

API Reference

Parameters

Parameter	Type	Required	Description
TimelineEventDataProvider	ITimelineEventDataProvider	Yes	Provider for timeline events data
OnEventSelected	EventCallback	No	Event triggered when a timeline item is clicked
Options	TimelineOptions	No	Configuration options for the timeline

TimelineOptions Properties

Property	Type	Default	Description
TimestampFormat	string	"yyyy-MM-dd"	Format string for date display
MaxEventSize	decimal	50	Maximum size for event indicators
Height	int	100	Height of the timeline in pixels
LineThickness	int	2	Thickness of the timeline line in pixels
ShowCurrentDateLine	bool	false	Whether to show a line for the current date
ContainerCssClass	string	"timeline-container"	CSS class for the container
LineClasses	string	"bg-secondary"	CSS classes for the timeline line
CurrentDateLineClasses	string	"bg-danger"	CSS classes for the current date line

TimelineEvent Properties

Property	Type	Required	Description
EventTime	DateTime	Yes	The time of the event
Size	decimal	No	Size of the event indicator (default: 1)
State	EventState	Yes	State of the event (Pending, Review_Required, etc.)
Title	string	No	Title/tooltip for the event

Examples

Basic Timeline with Current Date Line

<HorizontalTimeline 
    TimelineEventDataProvider="TimelineDataProvider" 
    OnEventSelected="HandleEventSelected" 
    Options="new TimelineOptions 
    {
        TimestampFormat = 'MMMM d, yyyy',
        ShowCurrentDateLine = true,
        Height = 150
    }" />

Custom Styling

<HorizontalTimeline 
    TimelineEventDataProvider="TimelineDataProvider" 
    OnEventSelected="HandleEventSelected" 
    Options="new TimelineOptions 
    {
        ContainerCssClass = 'my-custom-timeline',
        LineClasses = 'bg-primary',
        CurrentDateLineClasses = 'bg-warning'
    }" />

Best Practices

• Ensure the timeline data provider returns well-formatted and reasonable time ranges
• Handle the offline state appropriately when data cannot be fetched
• Use consistent date formatting that makes sense for your use case
• Set appropriate sizes for events to avoid visual clutter
• Consider accessibility when designing interactions with the timeline
• Test with different amounts of data to ensure good performance

Common Issues and Solutions

Issue: Events appear clustered or overlapping

Solution: Adjust the MaxEventSize option or ensure your data covers an appropriate time range.

Issue: Timeline not rendering properly

Solution: Verify CSS is properly loaded and check browser console for errors.

Issue: Events not appearing in expected positions

Solution: Verify that event times are properly formatted and within the expected range.

Issue: Click events not firing

Solution: Ensure the OnEventSelected callback is properly wired up and event handlers are correctly implemented.