Timeline Documentation

const saved = JSON.parse(timeline.getStatusForSave());

// At 12:30:15.250 the viewport fields include:
// { fy: 2026, fm: 8, fd: 13, fhr: 12, fmi: 30, fs: 15, fms: 250, ... }

const timeline = new Histropedia.Timeline(container);

// Load articles on to the timeline
timeline.load([
  {
    id: 1,
    title: 'Moon Landing',
    subtitle: 'Apollo 11',
    from: { year: 1969, month: 7, day: 16 },
    to: { year: 1969, month: 7, day: 24 }
  },
  {
    id: 2,
    title: 'World Wide Web',
    subtitle: 'Tim Berners-Lee proposal',
    from: { year: 1989, month: 3, day: 12 }
  }
]);

timeline.loadLanes([
  {
    id: 'people',
    title: 'People',
    layout: { heightWeight: 2 },
    article: {
      defaultCardLayout: 'landscape',
      defaultStyle: { width: 220 }
    }
  },
  {
    id: 'projects',
    title: 'Projects'
  }
]);

timeline.loadLaneArticles('projects', [
  {
    id: 'analytical-engine',
    title: 'Analytical Engine',
    from: { year: 1837 }
  },
  {
    id: 'difference-engine',
    title: 'Difference Engine',
    from: { year: 1822 }
  }
]);

const timeline = new Histropedia.Timeline(container);

// Load bands on to the timeline
timeline.loadTimeBands([
  {
    id: 1,
    title: "18th Century",
    from: { year: 1800, precision: 'century' }
  },
  {
    id: 2,
    title: "Presidency of John F. Kennedy",
    from: { year: 1961, month: 1, day: 20 },
    to: { year: 1963, month: 1, day: 22 }
  },
  {
    id: 3,
    title: "Digital Age (1970s - present)",
    from: { year: 1970, precision: 'decade' },
    isToPresent: true
  }
]);

// set new width and height
timeline.setOption({ width: 700, height: 400 });

// set mainLine size
timeline.setOption('style.mainLine.size', 10);

// set default article subheader height and color
timeline.setOption('article.defaultStyle.subheader', { height: 20, color: '#EEE' });

// get current animation settings
const animSettings = timeline.setOption('article.animation');

const container = document.getElementById('timeline');
const timeline = new Histropedia.Timeline(container);

// Keep the timeline sized with the container
const resize = () => {
  timeline.setSize(container.clientWidth, container.clientHeight);
};

window.addEventListener('resize', resize);
resize();

const onArticleSelect = (article) => {
  console.log('Selected article:', article.title);
};

timeline.on('article-select', onArticleSelect);

timeline.on('viewport-drag-start', (dragPayload, pointerEvent) => {
  console.log('Viewport drag started', dragPayload, pointerEvent);
  console.log(this); // Always the timeline instance for all handlers
});

const onZoom = ({ zoom }) => {
  console.log('Zoom level:', zoom);
};

timeline.on('zoom', onZoom);

// stop listening when the UI panel closes
timeline.off('zoom', onZoom);

// get the article with id = 1
const article = timeline.getArticleById(1);

// check article data (see article options for structure)
console.log(article.data);

// call article methods
article.setOption('hidePeriodLine', true);

timeline.on('timeline-state-change', saveTimelineState);

timeline.removeArticleById('apollo-11');
timeline.requestRedraw();

// get the currently active article
const article = timeline.getActiveArticle();

// check article data
console.log(article?.data);

// call article methods when available
article?.setOption('hidePeriodLine', true);

const peopleLane = timeline.getLaneById('people');

peopleLane?.setStyle('title.color', '#1e3a8a');
peopleLane?.hide();

timeline.moveLaneToIndex('people', 0);
timeline.moveLaneAfter('projects', 'people');
timeline.moveLaneUp('reference');
timeline.moveLaneDown('people');

// create Dmy for 5th Jan 1970
const date = new Histropedia.Dmy(1970, 1, 5);

timeline.setStartDate(date, {
  padding: 50,
  animation: {
    active: true,
    duration: 400,
    complete: () => console.log('done!')
  }
});

timeline.fitDateRange(
  { year: 1961, month: 1, day: 20 },
  { year: 1963, month: 11, day: 22 },
  {
    padding: { left: 80, right: 80 },
    animation: { active: true, duration: 500 }
  }
);

timeline.fitDateRange(
  '1000000000-06-15T12:00:00.000',
  '1000000000-06-15T12:00:00.001'
);

const article = timeline.getArticleById('apollo-11');

if (article) {
  timeline.fitArticleRange(article, {
    padding: 80,
    animation: { active: true, duration: 500 }
  });
}

// Fit all currently unfiltered articles
timeline.fitArticles();

// Fit only articles in a specific lane
timeline.fitArticles({
  padding: { left: 60, right: 60 },
  articleFilter: article => article.data.lane === 'projects',
  animation: { active: true, duration: 500 }
});

// 50 pixels backward in time (viewport moves left)
timeline.goToPixelAnim(-50);

// 1 million pixels forward in time (viewport moves right)
timeline.goToPixelAnim(1e6);

// whole canvas width, useful for next/previous navigation arrows
timeline.goToPixelAnim(timeline.width);

// ... with all available options set
const options = {
    duration: 400,
    easing: 'linear',
    complete: () => console.log('done!')
};
timeline.goToPixelAnim(timeline.width, options);

// create Dmy for 5th Jan 1970
const date = new Histropedia.Dmy(1970, 1, 5);

// jump to date, with date located on left edge of canvas
timeline.setStartDate(date);

// ... with date located 80px from the left edge
timeline.setStartDate(date, { padding: 80 });

// ... with animation
timeline.setStartDate(date, {
  padding: 80,
  animation: { active: true, duration: 500 }
});

// set date using string notation
timeline.setStartDate('1970-6'); // 1st June 1970

// set BCE date/time using string notation
timeline.setStartDate('-44-03-15 09:01');

// set an exact timestamp (fraction is right-padded to .250)
timeline.setStartDate('2026-08-13T12:30:15.25');

timeline.setCentreDate({ year: 1969, month: 7, day: 20 });

// Position the date 40px to the right of center
timeline.setCentreDate({ year: 1969, month: 7, day: 20 }, 40);

timeline.setCentreDate('2026-08-13T12:30:15.250');

timeline.setOption({
  bounds: {
    minDate: { year: 1950 },
    maxDate: { year: 2010 },
    overflow: 'elastic'
  }
});

timeline.settleDateBounds({ animate: false });

// read the current zoom
const currentZoom = timeline.getZoom();

// zoom out by a small amount
timeline.setZoom(currentZoom + 0.5);

// or, zoom in by a small amount
timeline.setZoom(currentZoom - 0.5);

// set zoom level 13.5, zooming from the centre of the canvas
timeline.setZoom(13.5);

// ... zooming from the left edge of the canvas
timeline.setZoom(13.5, 0);

// ... zooming from the right edge of the canvas
timeline.setZoom(13.5, timeline.width);

// hide currently active article and set date labels to green
timeline.getActiveArticle().hiddenByFilter = true;
timeline.options.style.dateLabel.major.color = 'green';

// redraw the timeline using the default `repositionRedraw`
timeline.requestRedraw();

// specify the most basic redraw for extra performance
timeline.requestRedraw(timeline.redraw);

// or request a full restack of articles
timeline.requestRedraw(timeline.defaultRedraw);

// hide currently active article and set date labels to green
timeline.getActiveArticle().hiddenByFilter = true;
timeline.options.style.dateLabel.major.color = 'green';

// redraw to see the results
timeline.redraw();

// For best performance call via requestRedraw instead
timeline.requestRedraw(timeline.redraw);

// hide currently active article and set date labels to green
timeline.getActiveArticle().hiddenByFilter = true;
timeline.options.style.dateLabel.major.color = 'green';

// redraw to see the changes
timeline.repositionRedraw();

// For best performance call via requestRedraw instead
timeline.requestRedraw(); // defaults to repositionRedraw

// hide currently active article and set date labels to green
timeline.getActiveArticle().hiddenByFilter = true;
timeline.options.style.dateLabel.major.color = 'green';

// redraw to see the changes with restacked articles
timeline.defaultRedraw();

// For best performance call via requestRedraw instead
timeline.requestRedraw(timeline.defaultRedraw);