moTimeline

Live demo

Get started

npm  ↗ npmjs.com/package/motimeline

npm install motimeline

ESM import

import MoTimeline from 'motimeline';
import 'motimeline/dist/moTimeline.css';

const tl = new MoTimeline('#my-timeline', {
  showBadge: true,
  showArrow: true,
  theme:     true,
});

UMD (no bundler)

<link   rel="stylesheet" href="moTimeline.css">
<script src="moTimeline.umd.js"></script>
<script>
  const tl = new MoTimeline('#my-timeline', { theme: true });
</script>

HTML structure (with theme) — what you write

<ul id="my-timeline">
  <li>
    <div class="mo-card">
      <div class="mo-card-image">           <!-- optional -->
        <img class="mo-banner" src="...">
        <img class="mo-avatar" src="...">   <!-- optional -->
      </div>
      <div class="mo-card-body">
        <h3>Title</h3>
        <p class="mo-meta">Date</p>
        <p>Text...</p>
      </div>
    </div>
  </li>
</ul>

Rendered DOM (after init) — what the library produces

Classes and elements added automatically by the library are highlighted. Right-column items also get mo-inverted js-mo-inverted on the <li>.

<ul class="mo-timeline mo-theme mo-twocol">
  <li class="mo-item js-mo-item">          <!-- added by library -->
    <span class="mo-arrow js-mo-arrow"></span>  <!-- injected if showArrow -->
    <span class="mo-badge js-mo-badge">1</span>   <!-- injected if showBadge -->
    <div class="mo-card">
      <div class="mo-card-image">
        <img class="mo-banner" src="...">
        <img class="mo-avatar" src="...">
      </div>
      <div class="mo-card-body">
        <h3>Title</h3>
        <p class="mo-meta">Date</p>
        <p>Text...</p>
      </div>
    </div>
  </li>
  <li class="mo-item js-mo-item mo-inverted js-mo-inverted">  <!-- right-column item -->
    ...
  </li>
</ul>

React wrapper

Save as Timeline.jsx and import it wherever you need a timeline.

import { useEffect, useRef } from 'react';
import MoTimeline from 'motimeline';
import 'motimeline/dist/moTimeline.css';

/**
 * items shape: [{ id, title, meta, text, banner, avatar, icon }]
 * All item fields are optional except a stable `id` for React keys.
 */
export default function Timeline({ items = [], options = {} }) {
  const ulRef  = useRef(null);
  const tlRef  = useRef(null);
  const lenRef = useRef(0);

  // Initialise once on mount
  useEffect(() => {
    tlRef.current = new MoTimeline(ulRef.current, options);
    lenRef.current = items.length;
    return () => tlRef.current?.destroy();
  }, []); // eslint-disable-line react-hooks/exhaustive-deps

  // When items array grows, pick up the new <li> elements React just rendered
  useEffect(() => {
    if (!tlRef.current) return;
    if (items.length > lenRef.current) {
      tlRef.current.initNewItems();
    } else {
      // Items removed or reordered — full reinit
      tlRef.current.destroy();
      tlRef.current = new MoTimeline(ulRef.current, options);
    }
    lenRef.current = items.length;
  }, [items]); // eslint-disable-line react-hooks/exhaustive-deps

  return (
    <ul ref={ulRef}>
      {items.map((item) => (
        <li key={item.id} {...(item.icon && { 'data-mo-icon': item.icon })}>
          <div className="mo-card">
            {item.banner && (
              <div className="mo-card-image">
                <img className="mo-banner" src={item.banner} alt="" />
                {item.avatar && <img className="mo-avatar" src={item.avatar} alt="" />}
              </div>
            )}
            <div className="mo-card-body">
              {item.title && <h3>{item.title}</h3>}
              {item.meta  && <p className="mo-meta">{item.meta}</p>}
              {item.text  && <p>{item.text}</p>}
            </div>
          </div>
        </li>
      ))}
    </ul>
  );
}

React — usage example

import { useState } from 'react';
import Timeline from './Timeline';

const INITIAL = [
  { id: '1', title: 'Project kickoff', meta: 'Jan 2024', text: 'Team aligned on goals and tech stack.' },
  { id: '2', title: 'Design system',   meta: 'Feb 2024', text: 'Component library shipped.',
    banner: 'banner.jpg', avatar: 'avatar.jpg' },
];

export default function App() {
  const [items, setItems] = useState(INITIAL);

  const addItem = () =>
    setItems(prev => [...prev, {
      id:    String(Date.now()),
      title: 'New event',
      meta:  'Just now',
      text:  'Added dynamically from React state.',
    }]);

  return (
    <>
      <Timeline
        items={items}
        options={{ showBadge: true, showArrow: true, theme: true }}
      />
      <button onClick={addItem}>Add item</button>
    </>
  );
}

Bootstrap

<!-- Bootstrap is fully compatible — just wrap in a container.
     No framework option needed; moTimeline handles its own layout. -->
<div class="container">
  <ul id="my-timeline">...</ul>
</div>

API

// Initialize (also called automatically in constructor)
const tl = new MoTimeline(elementOrSelector, options);

tl.refresh();                         // re-layout (called automatically on resize)
tl.initNewItems();                 // pick up manually appended <li> elements
tl.addItems(items);                 // create <li> from an array of objects (or JSON string) and append
tl.insertItem(item, index);        // insert a single item at index (omit for random position)
tl.filterByCategory(category);    // show only items whose data-categories includes category; null/'all' shows all
tl.clear();                           // remove all items and ad slots, reset counters — instance stays alive
tl.destroy();                        // remove listeners, reset DOM

addItems / insertItem — item schema

// All fields are optional except at least one of title / text
tl.addItems([
  {
    title:     "Project kickoff",        // <h3> heading
    meta:      "January 2024",           // date / subtitle line
    text:      "Kicked off the roadmap.", // body paragraph
    banner:    "images/banner.jpg",       // img.mo-banner (optional)
    avatar:    "images/avatar.jpg",       // img.mo-avatar (optional)
    icon:      "images/icon.svg",         // data-mo-icon on <li>, used by showCounterStyle:'image'
    fullWidth:  true,                      // span both columns (insertItem only)
    categories: ["development", "architecture"] // used by filterByCategory() — also accepts a space-separated string
  },
]);

// Insert at a specific position (or random when index is omitted):
tl.insertItem({ title: "Featured", text: "...", fullWidth: true }, 0);

// Mark any <li> as full-width manually, then refresh:
document.querySelector('li').classList.add('mo-fullwidth');
tl.refresh();

Infinite scroll recipe

moTimeline handles the layout — wire up an IntersectionObserver on a sentinel element to trigger your own data fetch, then call addItems().

<!-- Place a sentinel element right after the <ul> -->
<ul id="my-timeline"></ul>
<div id="sentinel"></div>

const tl       = new MoTimeline('#my-timeline', { theme: true, showBadge: true });
const sentinel  = document.getElementById('sentinel');
let   loading   = false;
let   page      = 1;
let   exhausted = false;

const observer = new IntersectionObserver(async (entries) => {
  if (!entries[0].isIntersecting || loading || exhausted) return;

  loading = true;
  const items = await fetchPage(page); // your own async data fetch

  if (items.length === 0) {
    exhausted = true;
    observer.disconnect();
  } else {
    tl.addItems(items);              // moTimeline creates <li> and lays out
    page++;
  }
  loading = false;
});

observer.observe(sentinel);

// Example fetch — replace with your real API call
async function fetchPage(page) {
  const res  = await fetch(`/api/events?page=${page}`);
  const data = await res.json();
  return data.items; // [{ title, meta, text, banner, avatar }, …]
}

Category filter recipe

Tag items with data-categories, then call filterByCategory() from your own filter buttons. The active filter is remembered — items added later via addItems() are filtered automatically.

<!-- Filter buttons (your own markup) -->
<div class="filters">
  <button data-cat="all">All</button>
  <button data-cat="development">Development</button>
  <button data-cat="architecture">Architecture</button>
</div>

<!-- Items tagged with categories -->
<ul id="my-timeline"></ul>

const tl = new MoTimeline('#my-timeline', { theme: true, showBadge: true });

// Load items with categories (array or space-separated string)
tl.addItems([
  { title: 'API cleanup',  meta: 'Jan 2025', text: '...', categories: ['development', 'architecture'] },
  { title: 'Sprint review', meta: 'Feb 2025', text: '...', categories: 'management' },
]);

// Wire filter buttons
document.querySelectorAll('.filters button').forEach(btn => {
  btn.addEventListener('click', () => {
    document.querySelectorAll('.filters button').forEach(b => b.classList.remove('active'));
    btn.classList.add('active');
    tl.filterByCategory(btn.dataset.cat); // 'all' → show everything
  });
});

// Active filter persists through lazy-loaded batches
tl.addItems(moreItemsFromServer); // new items auto-filtered to match current selection

CSS custom properties

#my-timeline {
  --mo-line-color:      #c7d2fe;
  --mo-badge-bg:        #4f46e5;
  --mo-badge-color:     #fff;
  --mo-badge-size:      26px;
  --mo-badge-font-size: 12px;
  --mo-arrow-color:     #c7d2fe;
  --mo-card-border-radius: 8px;
  --mo-avatar-size:     50px;
  --mo-card-margin:            0.5rem 1.25rem 0.5rem 0.5rem;
  --mo-card-margin-inverted:   0.5rem 0.5rem 0.5rem 1.25rem;
  --mo-card-margin-fullwidth:  0.5rem;
  --mo-animate-duration:        0.5s;
}

Options

Data attributes

CSS classes reference