moTimeline

Live demo

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

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

// Load items from a JSON array
tl.addItems([
  { title: 'Loaded from JSON', meta: 'March 2025', text: '…' },
  { title: 'Second JSON item', meta: 'April 2025', text: '…' },
]);

// Insert at a random position, or at a fixed index
tl.insertItem({ title: 'Inserted', meta: 'Just now', text: '…' });
tl.insertItem({ title: 'Full-width', fullWidth: true }, 2);

// Appending your own markup? Tell the library about it:
myUl.appendChild(li);
tl.initNewItems();

<!-- Items written as plain HTML — no addItems() needed. -->
<!-- data-mo-date feeds the date gutter used by 'stacked' and 'rows'. -->
<ul id="my-timeline">
  <li data-mo-date="Oct 2025">
    <div class="mo-card">
      <div class="mo-card-body">
        <h3>v1.5 shipped</h3>
        <p><span class="js-ts-ago" data-ts="2025-10-15T11:00:00"></span></p>
        <p>Dark mode, keyboard navigation and a new plugin API.</p>
      </div>
    </div>
  </li>
</ul>

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

// Refresh the relative labels on your own schedule
setInterval(updateTimestamps, 60000);

<!-- theme:false — the library handles layout only, -->
<!-- Bootstrap's own panels provide the card styling. -->
<div class="container">
  <ul id="my-timeline">
    <li>
      <div class="panel panel-primary">
        <div class="panel-heading"><h3>Beta launch</h3></div>
        <div class="panel-body">200 early users invited.</div>
      </div>
    </li>
  </ul>
</div>

const tl = new MoTimeline('#my-timeline', {
  showBadge: true,
  showArrow: true,
  theme:     false,   // no built-in card theme
});

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

// Tag each item — array or space-separated string
tl.addItems([
  { title: 'DI & .NET Cleanup', meta: '01/2026', text: '…',
    categories: ['architecture', 'development'] },
  { title: 'Sales Dashboard',  meta: '01/2024', text: '…',
    categories: ['database', 'management'] },
]);

// Show one category…
tl.filterByCategory('development');

// …or clear the filter again
tl.filterByCategory('all');   // null / '' work too

// The active filter is remembered and re-applied
// to items added later — infinite scroll stays correct.

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

const tl = new MoTimeline('#my-timeline', {
  theme:     true,
  showBadge: true,
  showArrow: true,
  adSlots: {
    mode:     'every_n',   // or 'random'
    interval: 3,           // a slot after every 3rd item
    style:    'card',      // or 'fullwidth' — spans both columns

    // Fires once per slot, at >= 50% visibility.
    // slotEl is the empty <li>; position is its child index.
    onEnterViewport(slotEl, position) {
      // Real AdSense usage:
      //   slotEl.innerHTML = '<ins class="adsbygoogle" ...></ins>';
      //   (adsbygoogle = window.adsbygoogle || []).push({});
      slotEl.innerHTML = '<div class="ad-box">Ad #' + position + '</div>';
    },
  },
});

tl.addItems(items);   // slots are injected automatically

// Wikimedia's on-this-day feed — public, no key, CC BY-SA.
const res  = await fetch(
  `https://api.wikimedia.org/feed/v1/wikipedia/${lang}/onthisday/${kind}/${mm}/${dd}`);
const json = await res.json();

// Map the feed onto the item schema — one line per field.
const items = json[kind].map(e => {
  const page = (e.pages || [])[0] || {};
  return {
    title:  page.normalizedtitle,
    meta:   String(e.year),
    date:   String(e.year),        // gutter for 'stacked' / 'rows'
    text:   e.text,
    banner: page.thumbnail?.source,
    icon:   page.thumbnail?.source,
  };
});

tl.clear();
tl.addItems(items);

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