Timeline Component API

Quick Start

1. Include the CSS and JavaScript

<link rel="stylesheet" href="styles/timeline.css">
<script src="javascript/timeline.js"></script>

2. Create a Timeline

<ol data-rsl-timeline data-timeline-variant="card">
    <li class="rsl-timeline-event" data-status="completed">
        <div class="rsl-timeline-marker"><i class="fas fa-check"></i></div>
        <div class="rsl-timeline-content">
            <time class="rsl-timeline-date">January 15, 2024</time>
            <h3 class="rsl-timeline-title">Project Started</h3>
            <p class="rsl-timeline-description">Initial planning and setup phase.</p>
        </div>
    </li>
    <li class="rsl-timeline-event" data-status="current">
        <div class="rsl-timeline-marker"></div>
        <div class="rsl-timeline-content">
            <time class="rsl-timeline-date">March 20, 2024</time>
            <h3 class="rsl-timeline-title">Development Phase</h3>
            <p class="rsl-timeline-description">Currently building features.</p>
        </div>
    </li>
    <li class="rsl-timeline-event" data-status="upcoming">
        <div class="rsl-timeline-marker"></div>
        <div class="rsl-timeline-content">
            <time class="rsl-timeline-date">June 1, 2024</time>
            <h3 class="rsl-timeline-title">Launch</h3>
            <p class="rsl-timeline-description">Public release planned.</p>
        </div>
    </li>
</ol>

Data Attributes API

Container Attributes

Attribute	Values	Default	Description
`data-rsl-timeline`	(marker)	-	Required. Marks element as a timeline container.
`data-timeline-orientation`	`vertical`, `horizontal`	`vertical`	Layout direction of the timeline.
`data-timeline-variant`	`default`, `minimal`, `card`, `split`, `compact`	`default`	Visual style variant.
`data-timeline-size`	`sm`, `md`, `lg`	`md`	Overall size of markers and spacing.
`data-timeline-connector`	`solid`, `dashed`, `dotted`, `gradient`, `none`	`solid`	Style of the connecting line.
`data-timeline-alternate`	(flag)	-	Alternate events left/right (vertical only).
`data-timeline-animate`	(flag)	-	Enable scroll-triggered animations.
`data-timeline-collapsible`	(flag)	-	Make event details expandable/collapsible.
`data-timeline-clickable`	(flag)	-	Enable click events on timeline items.
`data-timeline-group-by`	`date`, `month`, `year`, `category`	-	Group events by specified field.
`data-filterbus-subscribe`	filter key	-	Subscribe to FilterBus for external filtering.
`data-events`	JSON array	-	Events data in JSON format.

Event Item Attributes

Attribute	Values	Description
`data-event-id`	string	Unique identifier for the event.
`data-status`	`completed`, `current`, `upcoming`, `cancelled`	Event status (affects marker style).
`data-type`	`milestone`, `event`, `checkpoint`	Type of timeline item.
`data-category`	string	Category for filtering.

CSS Classes

Class	Description
`.rsl-timeline`	Base timeline container class.
`.rsl-timeline-vertical`	Vertical orientation (default).
`.rsl-timeline-horizontal`	Horizontal scrollable timeline.
`.rsl-timeline-card`	Card variant with elevated content.
`.rsl-timeline-minimal`	Minimal clean style.
`.rsl-timeline-compact`	Dense single-line view.
`.rsl-timeline-split`	Alternating left/right layout.
`.rsl-timeline-event`	Individual timeline event item.
`.rsl-timeline-marker`	Circular marker/dot element.
`.rsl-timeline-content`	Content wrapper.
`.rsl-timeline-date`	Date/time display.
`.rsl-timeline-title`	Event heading.
`.rsl-timeline-description`	Event description text.
`.rsl-timeline-badge`	Type/category badge.

JavaScript API

Method	Parameters	Description
`RSL.Timeline.init()`	-	Initialize all timelines on page.
`RSL.Timeline.create(element, options)`	element, options	Create/initialize a single timeline.
`RSL.Timeline.addEvent(element, eventData, index)`	element, data, index	Add an event dynamically.
`RSL.Timeline.removeEvent(element, id)`	element, id	Remove an event by ID.
`RSL.Timeline.updateEvent(element, id, data)`	element, id, data	Update an event's data.
`RSL.Timeline.filter(element, criteria)`	element, criteria	Filter events by criteria.
`RSL.Timeline.clearFilter(element)`	element	Clear all filters.
`RSL.Timeline.expand(element, id)`	element, id	Expand a collapsible event.
`RSL.Timeline.collapse(element, id)`	element, id	Collapse a collapsible event.
`RSL.Timeline.scrollTo(element, id)`	element, id	Scroll to a specific event.
`RSL.Timeline.getCurrent(element)`	element	Get the current/active event.
`RSL.Timeline.getEventsData(element)`	element	Get all events as JSON data.
`RSL.Timeline.setEvents(element, events)`	element, events	Replace all events with new data.
`RSL.Timeline.destroy(element)`	element	Clean up and destroy instance.

Events

Event	Detail Properties	Description
`rsl-timeline-init`	`config`	Fired when timeline is initialized.
`rsl-timeline-event-click`	`id`	Fired when an event is clicked.
`rsl-timeline-event-expand`	`id`	Fired when an event is expanded.
`rsl-timeline-event-collapse`	`id`	Fired when an event is collapsed.
`rsl-timeline-filter`	`criteria`, `visibleCount`	Fired when filter is applied.

Accessibility

WCAG 2.1 AA Compliant - The Timeline component includes comprehensive accessibility features.

Semantic HTML - Uses <ol> and <li> for proper list structure
ARIA Roles - role="list" and role="listitem"
Current Step - aria-current="step" on current event
Expandable Content - aria-expanded for collapsible events
Position Info - aria-setsize and aria-posinset
Screen Reader Text - Hidden text announces status
Focus Management - Visible focus indicators
Keyboard Navigation - Full keyboard support
Reduced Motion - Respects prefers-reduced-motion

Keyboard Navigation

Key	Action
`Tab`	Move focus between events
`Arrow Up/Down`	Navigate events (vertical timeline)
`Arrow Left/Right`	Navigate events (horizontal timeline)
`Enter` / `Space`	Expand/collapse event (if collapsible)
`Home`	Jump to first event
`End`	Jump to last event

FilterBus Integration

Timeline can subscribe to RSL's FilterBus for visibility filtering of events based on external filter controls. This is ideal for dashboard scenarios where filter buttons control which timeline events are displayed.

How It Works

Add data-filter-subscribe="key" to the timeline container to subscribe to a FilterBus channel
Events are filtered based on their data-status, data-category, or data-type attributes
Use data-filter-field="category" to specify which event attribute to filter by (default: "status")
"All" filter value shows all events (case-insensitive)
Supports search filtering with substring matching on title and description

FilterBus Attributes

Attribute	Type	Description
`data-filter-subscribe`	String	FilterBus key(s) to subscribe to. Supports comma-separated keys (e.g., "status,search").
`data-filter-field`	String	Which event attribute to match against filter value. Default: "status". Options: "status", "category", "type".
`data-filter-fade-only`	Boolean	If present, hidden events fade to 30% opacity instead of collapsing.

Example

<!-- Filter publishes to FilterBus -->
<div data-rsl-filter data-filter-key="status">
    <button data-filter-value="All">All</button>
    <button data-filter-value="completed">Completed</button>
    <button data-filter-value="current">In Progress</button>
    <button data-filter-value="upcoming">Upcoming</button>
</div>

<!-- Timeline subscribes to FilterBus -->
<ol data-rsl-timeline
    data-filter-subscribe="status"
    aria-label="Project Timeline">
    <li class="rsl-timeline-event" data-status="completed">
        <!-- Completed event -->
    </li>
    <li class="rsl-timeline-event" data-status="current">
        <!-- Current event -->
    </li>
    <li class="rsl-timeline-event" data-status="upcoming">
        <!-- Upcoming event -->
    </li>
</ol>

FilterBus Events

Event	Detail	Description
`rsl-timeline:filterbus-update`	`{ state, meta, visibleCount }`	Fired when timeline events are filtered via FilterBus.

See It Live: View the FilterBus Dashboard Demo to see Timeline working with other filterable components.

JSON API Integration

Timeline is fully integrated with RSL's JSON Layout API V2. You can create timelines declaratively using the timeline content type.

RSL.JSONLayout.renderLayout('#container', {
    version: 2,
    layoutId: 'my-timeline',
    breakpoints: { xs: 1 },
    items: [{
        content: {
            type: 'timeline',
            variant: 'card',
            orientation: 'vertical',
            events: [
                {
                    id: 'event-1',
                    date: 'March 2025',
                    title: 'Project Launch',
                    description: 'Initial release with core features',
                    status: 'completed',
                    icon: 'fa-rocket'
                },
                {
                    id: 'event-2',
                    date: 'April 2025',
                    title: 'Beta Release',
                    description: 'Public beta testing phase',
                    status: 'current',
                    icon: 'fa-flask'
                }
            ]
        }
    }]
});

See More: View the Component API Examples for comprehensive JSON API examples including horizontal timelines, collapsible events, and custom metadata.

Next Steps

See Examples

View examples.html for comprehensive demos

Try the Playground

Test features in playground.html

Explore Components

Browse all RSL components