Timeline Component

Data-driven timelines with multiple layouts and animations

⚠️ Component Deprecated The timeline() component has been superseded by the new unified Progression component, which combines Timeline and Roadmap functionality. Good news: Your existing timeline code continues to work! The timeline() method is now an alias for progression({ mode: 'timeline' }). View Progression Component →

Getting Started

Add a timeline to your page in three simple steps

Step 1: Add Container Element

Create a container div for the timeline:

<div id="my-timeline"></div>

Step 2: Include Domma

Add Domma CSS and JavaScript to your page:

<!-- CSS -->
<link rel="stylesheet" href="dist/domma.css">
<link rel="stylesheet" href="dist/elements.css">

<!-- JavaScript -->
<script src="dist/domma.min.js"></script>

Step 3: Initialize the Timeline

Call Domma.elements.progression() in timeline mode with your timeline data:

// Prepare your timeline data
const events = [
    {
        year: '2020',
        title: 'Project Start',
        description: 'Initial planning began'
    },
    {
        year: '2021',
        title: 'Beta Release',
        description: 'First public beta with core features'
    },
    {
        year: '2022',
        title: 'Version 1.0',
        description: 'Stable release'
    }
];

// Initialize the timeline
Domma.elements.progression('#my-timeline', {
    mode: 'timeline',
    items: events,           // Timeline data array
    layout: 'vertical',      // 'vertical' or 'centered'
    animation: true,         // Animate items on scroll
    animationDelay: 100      // Delay between items (ms)
});

Note: The timeline auto-generates the complete UI from your data array (no HTML structure required). Each item needs at least a title. Optional fields include year, description, icon, and image.

basic-timeline

A simple vertical timeline with data-driven content and smooth animations.

basic-timeline

<div id="basic-timeline"></div>

/**
 * basic-timeline - from public/showcase/elements/timeline.
 */
export function mount(root) {
    const basicTimelineData = [
                { year: '2023', title: 'Domma v0.1.0', description: 'Initial alpha release with DOM manipulation ($) and utilities (_)' },
                { year: 'Q1 2024', title: 'v0.3.0 Alpha', description: 'Added Dates (D), Storage (S), and HTTP (H) modules' },
                { year: 'Q2 2024', title: 'v0.5.0 Beta', description: 'Models (M) with reactive data binding and Forms module launched' },
                { year: 'Q3 2024', title: 'v0.8.0', description: 'Elements module with 22+ UI components and Tables module' },
                { year: 'Q4 2024', title: 'v0.12.0', description: 'Layout system, Blueprint schemas, and celebration effects' },
                { year: 'Jan 2026', title: 'v0.14.1', description: 'Enhanced celebrations with patron saint flower petal animations' }
            ];
            // Initialize all timelines
                // Basic timeline
    E.progression(root.querySelector('#basic-timeline'), {
                    mode: 'timeline',
                    items: basicTimelineData,
                    animation: true,
                    animationDelay: 100
                });
}

// JavaScript
const timelineData = [
    { year: '2020', title: 'Project Start', description: 'Initial planning and development began' },
    { year: '2021', title: 'Beta Release', description: 'First public beta with core features' },
    { year: '2022', title: 'Version 1.0', description: 'Stable release with full feature set' },
    { year: '2023', title: 'Major Update', description: 'Added new components and improved performance' }
];

Domma.elements.progression('#basic-timeline', {
    mode: 'timeline',
    items: timelineData,
    animation: true,
    animationDelay: 100
});

centered-timeline

A centered timeline layout with items alternating on both sides of a central line.

centered-timeline

<div id="centered-timeline"></div>

/**
 * centered-timeline - from public/showcase/elements/timeline.
 */
export function mount(root) {
    const companyHistory = [
                { year: '2023', title: 'Framework Concept', description: 'Domma envisioned as jQuery + Lodash + Moment unified toolkit' },
                { year: 'Q1 2024', title: 'Core Modules', description: 'DOM ($), Utils (_), Dates (D) modules implemented' },
                { year: 'Q2 2024', title: 'Reactive Models', description: 'Models (M) with pub/sub and two-way binding launched' },
                { year: 'Q3 2024', title: 'UI Components', description: 'Elements module with modal, tabs, carousel, and 20+ components' },
                { year: 'Q4 2024', title: 'Advanced Features', description: 'Forms, Tables, Blueprints, and celebration animations added' },
                { year: 'Jan 2026', title: 'Production Ready', description: 'Comprehensive testing suite and v1.0 roadmap established' }
            ];
                // Centered timeline
    E.progression(root.querySelector('#centered-timeline'), {
                    mode: 'timeline',
                    items: companyHistory,
                    layout: 'centered',
                    animation: true,
                    animationDelay: 120
                });
}

Domma.elements.progression('#centered-timeline', {
    mode: 'timeline',
    items: companyHistory,
    layout: 'centered',
    animation: true,
    theme: 'default'
});

horizontal-timeline

A horizontal scrollable timeline perfect for mobile devices or constrained layouts.

horizontal-timeline

<div id="horizontal-timeline"></div>

/**
 * horizontal-timeline - from public/showcase/elements/timeline.
 */
export function mount(root) {
    const projectMilestones = [
                { year: 'v0.8.0', title: 'Elements Module', description: 'Modal, tabs, tooltip, carousel, and 18 more components' },
                { year: 'v0.10.0', title: 'Forms & Tables', description: 'FormBuilder, validation, and DataTable functionality' },
                { year: 'v0.12.0', title: 'Blueprints', description: 'Unified schema system for models, forms, and CRUD' },
                { year: 'v0.14.1', title: 'Celebrations', description: '8 celebration themes with advanced canvas animations' }
            ];
                // Horizontal timeline
    E.progression(root.querySelector('#horizontal-timeline'), {
                    mode: 'timeline',
                    items: projectMilestones,
                    layout: 'horizontal',
                    animation: true,
                    animationDelay: 150
                });
}

Domma.elements.progression('#horizontal-timeline', {
    mode: 'timeline',
    items: projectMilestones,
    layout: 'horizontal',
    animation: true,
    animationDelay: 150
});

theme-variants

Different visual themes for various design contexts.

theme-variants

Minimal Theme

Corporate Theme

<div class="row g-4"><div class="col-6">
        <h3>Minimal Theme</h3>
        <div class="demo-container mb-4">
            <div id="minimal-timeline"></div>
        </div>
    </div>
    <div class="col-6">
        <h3>Corporate Theme</h3>
        <div class="demo-container mb-4">
            <div id="corporate-timeline"></div>
        </div>
    </div>
</div>

/**
 * theme-variants - from public/showcase/elements/timeline.
 */
export function mount(root) {
    const shortData = [
                { year: '2023', title: 'Alpha', description: 'Initial Domma framework concept and core modules' },
                { year: '2024', title: 'Beta', description: 'UI components, forms, and reactive models' },
                { year: '2026', title: 'v1.0', description: 'Production-ready stable release' }
            ];
                // Minimal theme
    E.progression(root.querySelector('#minimal-timeline'), {
                    mode: 'timeline',
                    items: shortData,
                    theme: 'minimal',
                    animation: true
                });
                // Corporate theme
    E.progression(root.querySelector('#corporate-timeline'), {
                    mode: 'timeline',
                    items: shortData,
                    theme: 'corporate',
                    animation: true
                });
}

// Minimal theme
Domma.elements.progression('#minimal-timeline', {
    mode: 'timeline',
    items: shortData,
    theme: 'minimal',
    animation: true
});

// Corporate theme
Domma.elements.progression('#corporate-timeline', {
    mode: 'timeline',
    items: shortData,
    theme: 'corporate',
    animation: true
});

interactive-timeline

A clickable timeline with event handling and dynamic updates.

interactive-timeline

Clicked: Click on timeline items to see event handling in action!

<div id="interactive-timeline"></div>
<div class="mt-3">
    <button type="button" class="btn btn-primary" id="add-item">Add New Item</button>
    <button type="button" class="btn btn-secondary" id="change-layout">Toggle Layout</button>
</div>
<div class="mt-3">
    <div class="alert alert-info" id="click-output" data-if="clicked.value">
        <strong>Clicked:</strong> <span data-bind-text="clicked.value">Click on timeline items to see event handling in action!</span>
    </div>
</div>

/**
 * interactive-timeline - from public/showcase/elements/timeline.
 *
 * The "Clicked:" read-out is bound: it appears once an item has been clicked.
 */
export function mount(root) {
    const interactiveData = [
        { year: '2023', title: 'Core Modules', description: 'DOM ($), Utils (_), Dates (D) foundation' },
        { year: '2024', title: 'UI Components', description: 'Elements module with 22+ components' },
        { year: '2026', title: 'Advanced Features', description: 'Celebrations, Blueprints, and Router enhancements' }
    ];
    const clicked = M.observable('');
    const handle = M.applyBindings({clicked}, root);

    // Interactive timeline
    const timeline = E.progression(root.querySelector('#interactive-timeline'), {
        mode: 'timeline',
        items: interactiveData,
        clickable: true,
        animation: true,
        onItemClick: (item, index, element) => {
            clicked.value = `${item.title} (${item.year})`;
        }
    });
    // Interactive controls
    $(root).find('#add-item').on('click', () => {
        const years = ['2025', '2026', '2027', '2028'];
        const titles = ['Future Update', 'Next Release', 'Major Milestone', 'Innovation'];
        const descriptions = [
            'Exciting new features coming soon!',
            'Enhanced performance and capabilities',
            'Revolutionary improvements ahead',
            'Cutting-edge technology integration'
        ];

        const randomIndex = Math.floor(Math.random() * years.length);
        const newItem = {
            year: years[randomIndex],
            title: titles[randomIndex],
            description: descriptions[randomIndex]
        };
        timeline.addItem(newItem);
    });
    let isVertical = true;
    $(root).find('#change-layout').on('click', () => {
        timeline.setLayout(isVertical ? 'horizontal' : 'vertical');
        isVertical = !isVertical;
        // An arrow function has no `this` of its own: name the button.
        $(root).find('#change-layout').text(isVertical ? 'Switch to Horizontal' : 'Switch to Vertical');
    });

    return () => {
        handle.dispose();
        timeline?.destroy?.();
    };
}

const timeline = Domma.elements.progression('#interactive-timeline', {
    mode: 'timeline',
    items: interactiveData,
    clickable: true,
    onItemClick: (item, index, element) => {
        $('#click-output').show().html(
            `Clicked: ${item.title} (${item.year})`
        );
    }
});

// Add new item
$('#add-item').on('click', () => {
    const newItem = {
        year: '2026',
        title: 'Future Update',
        description: 'Exciting new features coming soon!'
    };
    timeline.addItem(newItem);
});

// Toggle layout
let isVertical = true;
$('#change-layout').on('click', () => {
    timeline.setLayout(isVertical ? 'horizontal' : 'vertical');
    isVertical = !isVertical;
});

api-reference

Constructor

Domma.elements.progression(selector, {mode: 'timeline', ...})

Creates a new timeline instance. Domma.elements.timeline(selector, options) was removed in 0.58 - progression(selector, {mode: 'timeline'}) is the call.

Options

Option	Type	Default	Description
`items`	Array	`[]`	Array of timeline item objects
`layout`	String	`'vertical'`	Layout type: 'vertical', 'horizontal', 'centered'
`animation`	Boolean	`true`	Enable entrance animations
`animationDelay`	Number	`100`	Delay between item animations (ms)
`theme`	String	`'default'`	Visual theme: 'default', 'minimal', 'corporate'
`clickable`	Boolean	`false`	Enable click events on timeline items
`onItemClick`	Function	`null`	Callback for item clicks: (item, index, element)

Methods

setItems(items)

Replace all timeline items with new data.

addItem(item)

Add a single item to the end of the timeline.

getItems()

Get a copy of all timeline items.

setLayout(layout)

Change the timeline layout: 'vertical', 'horizontal', 'centered'.

refresh()

Re-render the timeline with current data and settings.

Item Object Structure

{
    year: '2024',           // String - displayed in the year badge
    title: 'Event Title',   // String - main heading
    description: '...'      // String - descriptive text
}

CSS Customisation

Override these CSS variables to customise Timeline appearance and match your design system.

Variable	Default	Controls
`--dm-primary`	`var(--dm-blue-600)`	Timeline line/marker colour
`--dm-surface`	`var(--dm-white)`	Event card background
`--dm-border`	`var(--dm-slate-300)`	Event card border

Example Override

:root {
    /* Custom timeline accent */
    --dm-primary: #8b5cf6;
}

Full CSS Customisation Cheat-Sheet →