JavaScript Document timeline Property

What You’ll Learn

Document.timeline is a read-only instance property that returns the document’s default DocumentTimeline for the Web Animations API. Learn currentTime, Performance.timeOrigin, inactive null states, and five examples with try-it labs.

Introduction

CSS transitions and the Web Animations API need a shared clock so animations stay in sync. Every document has one default timeline that tracks elapsed time since the page’s performance time origin.

MDN: the timeline read-only property represents the default timeline of the current document. This timeline is a special instance of DocumentTimeline. It is unique to each document and persists for the lifetime of the document, including calls to Document.open().

Related Document tutorials: readyState, prerendering, hidden, Document constructor.

Understanding Document.timeline

A read-only instance property from the Web Animations spec.

• Value — DocumentTimeline object (MDN).
• Scope — one default timeline per document; survives document.open() (MDN).
• currentTime — ms since Performance.timeOrigin when active (MDN).
• Inactive — currentTime is null before time origin or on non-active documents (MDN).
• Status — Baseline Widely available (since July 2020, MDN).

📝 Syntax

document.timeline

Value

A DocumentTimeline object (MDN).

Read currentTime

const time = document.timeline.currentTime;
console.log("Document timeline (ms):", time);

⚖️ Time & Animation APIs

Examples Gallery

Examples follow MDN Document: timeline. Each includes a try-it lab you can run in the browser.

const tl = document.timeline;
console.log(tl.constructor.name); // "DocumentTimeline"

DocumentTimeline

const ms = document.timeline.currentTime;
console.log("Timeline ms:", ms);

Timeline ms: 1234.5

console.log({
  timeOrigin: performance.timeOrigin,
  timelineNow: document.timeline.currentTime,
  performanceNow: performance.now()
});

{ timeOrigin: 171..., timelineNow: 500, performanceNow: 500 }

const box = document.querySelector(".box");
const anim = box.animate(
  [{ opacity: 0 }, { opacity: 1 }],
  { duration: 1000, fill: "forwards" }
);

console.log("Animation timeline:", anim.timeline === document.timeline);

Animation timeline: true

function getTimelineMs() {
  const t = document.timeline.currentTime;
  if (t === null) {
    return "Timeline inactive (currentTime is null)";
  }
  return `Active at ${t} ms`;
}

console.log(getTimelineMs());

Active at 842.1 ms

🚀 Common Use Cases

• Web Animations — default clock for element.animate().
• Animation debugging — log currentTime when effects desync.
• Custom timelines — compare against document default before overriding.
• Performance correlation — relate animations to performance.now().
• SPA navigation — understand timeline persistence after document.open().
• Teaching WAAPI — explain where animation time comes from.

📝 Notes

• MDN: Baseline Widely available (since July 2020) — no Deprecated / Experimental / Non-standard banner.
• Timeline persists across document.open() for the same document (MDN).
• Before time origin or on non-active documents, currentTime is null (MDN).
• Prefer element.animate() or CSS animations for effects; timeline is the underlying clock.
• Related: readyState, hidden, Document constructor.

💡 Best Practices