Timeline

An ordered sequence of events — a run history, an audit trail, an approval queue. Each item is a marker on a connecting line, with a heading, an optional date and a body.

The root is a role="list", so assistive tech announces how many events there are before reading them.

Default

An item takes a title and an optional date; its children are the body. Give an item no date at all and it is simply a labelled step.

AstroReactSvelteVue

PreviewCode

Opened

January 12, 2026

Merge request !402 opened against main.

Reviewed

February 3, 2026

Three findings raised; two resolved in follow-up commits.

Awaiting approval

Blocked on a human reviewer.

---
import { Timeline, TimelineItem } from "../../index";

const RELEASED = new Date(2026, 0, 12);
const REVIEWED = new Date(2026, 1, 3);
---

<Timeline>
  <TimelineItem title="Opened" date={RELEASED} locale="en-US">
    Merge request !402 opened against <code>main</code>.
  </TimelineItem>
  <TimelineItem title="Reviewed" date={REVIEWED} locale="en-US">
    Three findings raised; two resolved in follow-up commits.
  </TimelineItem>
  <TimelineItem title="Awaiting approval">
    Blocked on a human reviewer.
  </TimelineItem>
</Timeline>

Opened

January 12, 2026

Merge request !402 opened against main.

Reviewed

February 3, 2026

Three findings raised; two resolved in follow-up commits.

Awaiting approval

Blocked on a human reviewer.

import { Timeline, TimelineItem } from "../Timeline";

const RELEASED = new Date(2026, 0, 12);
const REVIEWED = new Date(2026, 1, 3);

export default function DefaultDemo() {
  return (
    <Timeline>
      <TimelineItem title="Opened" date={RELEASED} locale="en-US">
        Merge request !402 opened against <code>main</code>.
      </TimelineItem>
      <TimelineItem title="Reviewed" date={REVIEWED} locale="en-US">
        Three findings raised; two resolved in follow-up commits.
      </TimelineItem>
      <TimelineItem title="Awaiting approval">
        Blocked on a human reviewer.
      </TimelineItem>
    </Timeline>
  );
}

Opened

January 12, 2026

Merge request !402 opened against main.

Reviewed

February 3, 2026

Three findings raised; two resolved in follow-up commits.

Awaiting approval

Blocked on a human reviewer.

<script lang="ts">
  import { Timeline, TimelineItem } from "../index.js";

  const RELEASED = new Date(2026, 0, 12);
  const REVIEWED = new Date(2026, 1, 3);
</script>

<Timeline>
  <TimelineItem title="Opened" date={RELEASED} locale="en-US">
    Merge request !402 opened against <code>main</code>.
  </TimelineItem>
  <TimelineItem title="Reviewed" date={REVIEWED} locale="en-US">
    Three findings raised; two resolved in follow-up commits.
  </TimelineItem>
  <TimelineItem title="Awaiting approval">
    Blocked on a human reviewer.
  </TimelineItem>
</Timeline>

Opened

January 12, 2026

Merge request !402 opened against main.

Reviewed

February 3, 2026

Three findings raised; two resolved in follow-up commits.

Awaiting approval

Blocked on a human reviewer.

<script setup lang="ts">
import { Timeline, TimelineItem } from "@pindoba/vue-timeline";

const RELEASED = new Date(2026, 0, 12);
const REVIEWED = new Date(2026, 1, 3);
</script>

<template>
  <Timeline>
    <TimelineItem title="Opened" :date="RELEASED" locale="en-US">
      Merge request !402 opened against <code>main</code>.
    </TimelineItem>
    <TimelineItem title="Reviewed" :date="REVIEWED" locale="en-US">
      Three findings raised; two resolved in follow-up commits.
    </TimelineItem>
    <TimelineItem title="Awaiting approval">
      Blocked on a human reviewer.
    </TimelineItem>
  </Timeline>
</template>

Dates

date takes a single Date or a [start, end] range. Formatting lives in core (formatTimelineDate) rather than in each template, so all four frameworks print the same string — worth knowing because the rules have edge cases worth being consistent about:

With no title, the formatted date is promoted to the heading instead of rendering an empty one above it.
A range whose end is today reads as ”… – now”. An item still in progress is the common case on a timeline, and repeating today’s date would make a running item look closed.
Malformed input degrades to Invalid date rather than throwing mid-render.

Pass locale to format for a specific BCP 47 locale; it defaults to the runtime’s.

AstroReactSvelteVue

PreviewCode

January 5, 2026

No title, so the date becomes the heading.

Closed range

January 5, 2026 - March 9, 2026

Both ends are shown.

Still running

January 5, 2026 - now

A range ending today reads as "… – now".

---
import { Timeline, TimelineItem } from "../../index";

const START = new Date(2026, 0, 5);
const END = new Date(2026, 2, 9);
---

<Timeline>
  <TimelineItem date={START} locale="en-US">
    No title, so the date becomes the heading.
  </TimelineItem>
  <TimelineItem title="Closed range" date={[START, END]} locale="en-US">
    Both ends are shown.
  </TimelineItem>
  <TimelineItem title="Still running" date={[START, new Date()]} locale="en-US">
    A range ending today reads as "… – now".
  </TimelineItem>
</Timeline>

January 5, 2026

No title, so the date becomes the heading.

Closed range

January 5, 2026 - March 9, 2026

Both ends are shown.

Still running

January 5, 2026 - now

A range ending today reads as “… – now”.

import { Timeline, TimelineItem } from "../Timeline";

const START = new Date(2026, 0, 5);
const END = new Date(2026, 2, 9);

export default function DatesDemo() {
  return (
    <Timeline>
      <TimelineItem date={START} locale="en-US">
        No title, so the date becomes the heading.
      </TimelineItem>
      <TimelineItem title="Closed range" date={[START, END]} locale="en-US">
        Both ends are shown.
      </TimelineItem>
      <TimelineItem
        title="Still running"
        date={[START, new Date()]}
        locale="en-US"
      >
        A range ending today reads as &ldquo;… – now&rdquo;.
      </TimelineItem>
    </Timeline>
  );
}

January 5, 2026

No title, so the date becomes the heading.

Closed range

January 5, 2026 - March 9, 2026

Both ends are shown.

Still running

January 5, 2026 - now

A range ending today reads as "… – now".

<script lang="ts">
  import { Timeline, TimelineItem } from "../index.js";

  const START = new Date(2026, 0, 5);
  const END = new Date(2026, 2, 9);
</script>

<Timeline>
  <TimelineItem date={START} locale="en-US">
    No title, so the date becomes the heading.
  </TimelineItem>
  <TimelineItem title="Closed range" date={[START, END]} locale="en-US">
    Both ends are shown.
  </TimelineItem>
  <TimelineItem title="Still running" date={[START, new Date()]} locale="en-US">
    A range ending today reads as "… – now".
  </TimelineItem>
</Timeline>

January 5, 2026

No title, so the date becomes the heading.

Closed range

January 5, 2026 - March 9, 2026

Both ends are shown.

Still running

January 5, 2026 - now

A range ending today reads as "… – now".

<script setup lang="ts">
import { Timeline, TimelineItem } from "@pindoba/vue-timeline";

const START = new Date(2026, 0, 5);
const END = new Date(2026, 2, 9);
const RUNNING: [Date, Date] = [START, new Date()];
const CLOSED: [Date, Date] = [START, END];
</script>

<template>
  <Timeline>
    <TimelineItem :date="START" locale="en-US">
      No title, so the date becomes the heading.
    </TimelineItem>
    <TimelineItem title="Closed range" :date="CLOSED" locale="en-US">
      Both ends are shown.
    </TimelineItem>
    <TimelineItem title="Still running" :date="RUNNING" locale="en-US">
      A range ending today reads as "… – now".
    </TimelineItem>
  </Timeline>
</template>

Feedback

feedback tints an item’s marker and its connecting line, so a run history can carry its own status at a glance. neutral is special-cased to a surface-and-border marker rather than a solid fill, which keeps a routine step from competing with the ones that matter.

AstroReactSvelteVue

PreviewCode

Primary

Default marker colour.

Neutral

A colourless step.

Success

The pipeline passed.

Warning

Bundle size grew by 40kb.

Danger

A hardcoded secret was found.

---
import { Timeline, TimelineItem } from "../../index";
---

<Timeline>
  <TimelineItem title="Primary" feedback="primary"
    >Default marker colour.</TimelineItem
  >
  <TimelineItem title="Neutral" feedback="neutral"
    >A colourless step.</TimelineItem
  >
  <TimelineItem title="Success" feedback="success"
    >The pipeline passed.</TimelineItem
  >
  <TimelineItem title="Warning" feedback="warning"
    >Bundle size grew by 40kb.</TimelineItem
  >
  <TimelineItem title="Danger" feedback="danger"
    >A hardcoded secret was found.</TimelineItem
  >
</Timeline>

Primary

Default marker colour.

Neutral

A colourless step.

Success

The pipeline passed.

Warning

Bundle size grew by 40kb.

Danger

A hardcoded secret was found.

import { Timeline, TimelineItem } from "../Timeline";

export default function FeedbackDemo() {
  return (
    <Timeline>
      <TimelineItem title="Primary" feedback="primary">
        Default marker colour.
      </TimelineItem>
      <TimelineItem title="Neutral" feedback="neutral">
        A colourless step.
      </TimelineItem>
      <TimelineItem title="Success" feedback="success">
        The pipeline passed.
      </TimelineItem>
      <TimelineItem title="Warning" feedback="warning">
        Bundle size grew by 40kb.
      </TimelineItem>
      <TimelineItem title="Danger" feedback="danger">
        A hardcoded secret was found.
      </TimelineItem>
    </Timeline>
  );
}

Primary

Default marker colour.

Neutral

A colourless step.

Success

The pipeline passed.

Warning

Bundle size grew by 40kb.

Danger

A hardcoded secret was found.

<script lang="ts">
  import { Timeline, TimelineItem } from "../index.js";
</script>

<Timeline>
  <TimelineItem title="Primary" feedback="primary"
    >Default marker colour.</TimelineItem
  >
  <TimelineItem title="Neutral" feedback="neutral"
    >A colourless step.</TimelineItem
  >
  <TimelineItem title="Success" feedback="success"
    >The pipeline passed.</TimelineItem
  >
  <TimelineItem title="Warning" feedback="warning"
    >Bundle size grew by 40kb.</TimelineItem
  >
  <TimelineItem title="Danger" feedback="danger"
    >A hardcoded secret was found.</TimelineItem
  >
</Timeline>

Primary

Default marker colour.

Neutral

A colourless step.

Success

The pipeline passed.

Warning

Bundle size grew by 40kb.

Danger

A hardcoded secret was found.

<script setup lang="ts">
import { Timeline, TimelineItem } from "@pindoba/vue-timeline";
</script>

<template>
  <Timeline>
    <TimelineItem title="Primary" feedback="primary"
      >Default marker colour.</TimelineItem
    >
    <TimelineItem title="Neutral" feedback="neutral"
      >A colourless step.</TimelineItem
    >
    <TimelineItem title="Success" feedback="success"
      >The pipeline passed.</TimelineItem
    >
    <TimelineItem title="Warning" feedback="warning"
      >Bundle size grew by 40kb.</TimelineItem
    >
    <TimelineItem title="Danger" feedback="danger"
      >A hardcoded secret was found.</TimelineItem
    >
  </Timeline>
</template>

Icons

Each item takes an icon for the marker — a snippet in Svelte, a node in React, an icon slot in Vue, and a component in Astro. Without one the marker is a plain dot.

#Default

#Dates

#Feedback

#Icons

Default

Dates

Feedback

Icons