Timeline

A sequence of entries on a rail: an activity log, a comment thread, an audit trail or a step tracker. Every entry is the same anatomy, so these mix freely in one list:

a marker on the rail: a dot, a Stamp with an icon, an Avatar, or nothing
a header: a Banner with an optional eyebrow (a time, an id, a stage), the heading, and the meta (usually the date) on its own muted line
an optional body: text, a Card, a quote
an optional actions row: buttons, reactions, reply counts

The root is a role="list" and every entry a role="listitem", so assistive tech announces how many entries there are before reading them.

Activity log

A dense log mixes one-line events with richer entries. Leave the marker empty for a quiet dot, or drop a Stamp or Avatar into it. Whatever you put there is resized to the rail’s marker box, so a size="lg" stamp still lines up. Put the actor and the action in the heading slot: <strong>, <b> and <a> read bolder than the surrounding text.

TimelineSeparator starts a new section (“Today”, “Last week”). Its label is a Banner eyebrow (the same small uppercase kicker used across the system), set at the row’s start edge, and the rail breaks around it, so each section gets its own line. TimelineCollapse hides a run of entries behind a “Show N more” toggle.

PreviewCode

Today

Marta Silva renamed the issue to Retune the danger ramp

12 minutes ago

Lucía Ortega commented

40 minutes ago

The 600 step fails AA on the dark page by a hair. Nudging lightness by two points fixes it without touching the hue.

Kenji Mori asked to merge tokens/danger-600

2 hours ago

Last week

Checks passed on main

6 days ago

---
// GENERATED from packages/demos/timeline/activity.demo.tsx — edit the source, not this file.
import Avatar from "@pindoba/astro-avatar";
import Button from "@pindoba/astro-button";
import Card from "@pindoba/astro-card";
import Stamp from "@pindoba/astro-stamp";
import {
  Timeline,
  TimelineCollapse,
  TimelineItem,
  TimelineSeparator,
} from "@pindoba/astro-timeline";
import { GitPullRequest, Tag, CircleCheck } from "@lucide/astro";

const NOW = new Date(2026, 9, 16, 15, 0);
const ago = (minutes: number) => new Date(NOW.getTime() - minutes * 60_000);
const shared = { now: NOW, locale: "en-US", dateFormat: "relative" } as const;
---

<Timeline size="sm">
  <TimelineSeparator label="Today" />
  <TimelineItem {...shared} date={ago(12)}>
    <Fragment slot="heading">
      <strong>Marta Silva</strong> renamed the issue to{" "}
      <strong>Retune the danger ramp</strong>
    </Fragment>
  </TimelineItem>
  <TimelineItem {...shared} date={ago(40)}>
    <Avatar
      slot="marker"
      name="Lucía Ortega"
      src="https://i.pravatar.cc/96?u=lucia"
    />
    <Fragment slot="heading">
      <strong>Lucía Ortega</strong> commented
    </Fragment>
    <Card size="sm" border="default">
      The 600 step fails AA on the dark page by a hair. Nudging lightness by two
      points fixes it without touching the hue.
    </Card>
  </TimelineItem>
  <TimelineItem {...shared} date={ago(95)}>
    <Stamp slot="marker" tone="primary" shape="circle">
      <GitPullRequest />
    </Stamp>
    <Fragment slot="heading">
      <strong>Kenji Mori</strong> asked to merge{" "}
      <strong>tokens/danger-600</strong>
    </Fragment>
    <Fragment slot="actions">
      <Button size="sm" emphasis="secondary">
        Decline
      </Button>
      <Button size="sm" emphasis="primary">
        Approve
      </Button>
    </Fragment>
  </TimelineItem>
  <TimelineCollapse count={3}>
    <TimelineItem {...shared} date={ago(130)}>
      <Fragment slot="heading">
        <strong>Kenji Mori</strong> pushed 2 commits
      </Fragment>
    </TimelineItem>
    <TimelineItem {...shared} date={ago(160)}>
      <Stamp slot="marker" emphasis="ghost" shape="circle">
        <Tag />
      </Stamp>
      <Fragment slot="heading">
        <strong>Marta Silva</strong> added the <strong>color</strong> label
      </Fragment>
    </TimelineItem>
    <TimelineItem {...shared} date={ago(200)}>
      <Fragment slot="heading">
        <strong>Marta Silva</strong> opened the issue
      </Fragment>
    </TimelineItem>
  </TimelineCollapse>
  <TimelineSeparator label="Last week" />
  <TimelineItem {...shared} date={ago(60 * 24 * 6)} tone="success">
    <Stamp slot="marker" tone="success" shape="circle">
      <CircleCheck />
    </Stamp>
    <Fragment slot="heading">
      Checks passed on <strong>main</strong>
    </Fragment>
  </TimelineItem>
</Timeline>

Today

Marta Silva renamed the issue to Retune the danger ramp

12 minutes ago

Lucía Ortega commented

40 minutes ago

The 600 step fails AA on the dark page by a hair. Nudging lightness by two points fixes it without touching the hue.

Kenji Mori asked to merge tokens/danger-600

2 hours ago

Last week

Checks passed on main

6 days ago

<script lang="ts">
  // GENERATED from packages/demos/timeline/activity.demo.tsx — edit the source, not this file.
  import Avatar from "@pindoba/svelte-avatar";
  import Button from "@pindoba/svelte-button";
  import Card from "@pindoba/svelte-card";
  import Stamp from "@pindoba/svelte-stamp";
  import Timeline from "@pindoba/svelte-timeline";
  import {
    TimelineCollapse,
    TimelineItem,
    TimelineSeparator,
  } from "@pindoba/svelte-timeline";
  import LucideGitPullRequest from "@lucide/svelte/icons/git-pull-request";
  import LucideTag from "@lucide/svelte/icons/tag";
  import LucideCircleCheck from "@lucide/svelte/icons/circle-check";

  const NOW = new Date(2026, 9, 16, 15, 0);
  const ago = (minutes: number) => new Date(NOW.getTime() - minutes * 60_000);
  const shared = { now: NOW, locale: "en-US", dateFormat: "relative" } as const;
</script>

<Timeline size="sm">
  <TimelineSeparator label="Today"></TimelineSeparator>
  <TimelineItem {...shared} date={ago(12)}>
    {#snippet heading()}
      <strong> Marta Silva </strong> renamed the issue to
      <strong> Retune the danger ramp </strong>
    {/snippet}
  </TimelineItem>
  <TimelineItem {...shared} date={ago(40)}>
    {#snippet marker()}
      <Avatar name="Lucía Ortega" src="https://i.pravatar.cc/96?u=lucia"
      ></Avatar>
    {/snippet}
    {#snippet heading()}
      <strong> Lucía Ortega </strong> commented
    {/snippet}
    <Card size="sm" border="default">
      The 600 step fails AA on the dark page by a hair. Nudging lightness by two
      points fixes it without touching the hue.
    </Card>
  </TimelineItem>
  <TimelineItem {...shared} date={ago(95)}>
    {#snippet marker()}
      <Stamp tone="primary" shape="circle">
        <LucideGitPullRequest />
      </Stamp>
    {/snippet}
    {#snippet heading()}
      <strong> Kenji Mori </strong> asked to merge
      <strong> tokens/danger-600 </strong>
    {/snippet}
    {#snippet actions()}
      <Button size="sm" emphasis="secondary">Decline</Button>
      <Button size="sm" emphasis="primary">Approve</Button>
    {/snippet}
  </TimelineItem>
  <TimelineCollapse count={3}>
    <TimelineItem {...shared} date={ago(130)}>
      {#snippet heading()}
        <strong> Kenji Mori </strong> pushed 2 commits
      {/snippet}
    </TimelineItem>
    <TimelineItem {...shared} date={ago(160)}>
      {#snippet marker()}
        <Stamp emphasis="ghost" shape="circle">
          <LucideTag />
        </Stamp>
      {/snippet}
      {#snippet heading()}
        <strong> Marta Silva </strong> added the <strong> color </strong> label
      {/snippet}
    </TimelineItem>
    <TimelineItem {...shared} date={ago(200)}>
      {#snippet heading()}
        <strong> Marta Silva </strong> opened the issue
      {/snippet}
    </TimelineItem>
  </TimelineCollapse>
  <TimelineSeparator label="Last week"></TimelineSeparator>
  <TimelineItem {...shared} date={ago(60 * 24 * 6)} tone="success">
    {#snippet marker()}
      <Stamp tone="success" shape="circle">
        <LucideCircleCheck />
      </Stamp>
    {/snippet}
    {#snippet heading()}
      Checks passed on <strong> main </strong>
    {/snippet}
  </TimelineItem>
</Timeline>

Today

Marta Silva renamed the issue to Retune the danger ramp

12 minutes ago

Lucía Ortega commented

40 minutes ago

The 600 step fails AA on the dark page by a hair. Nudging lightness by two points fixes it without touching the hue.

Kenji Mori asked to merge tokens/danger-600

2 hours ago

Last week

Checks passed on main

6 days ago

// GENERATED from packages/demos/timeline/activity.demo.tsx — edit the source, not this file.
import { Avatar } from "@pindoba/solid-avatar";
import { Button } from "@pindoba/solid-button";
import { Card } from "@pindoba/solid-card";
import { Stamp } from "@pindoba/solid-stamp";
import {
  Timeline,
  TimelineCollapse,
  TimelineItem,
  TimelineSeparator,
} from "@pindoba/solid-timeline";

const NOW = new Date(2026, 9, 16, 15, 0);
const ago = (minutes: number) => new Date(NOW.getTime() - minutes * 60_000);
const shared = { now: NOW, locale: "en-US", dateFormat: "relative" } as const;
export default function ActivityDemo() {
  return (
    <Timeline size="sm">
      <TimelineSeparator label="Today" />
      <TimelineItem
        {...shared}
        date={ago(12)}
        heading={
          <>
            <strong>Marta Silva</strong> renamed the issue to{" "}
            <strong>Retune the danger ramp</strong>
          </>
        }
      />
      <TimelineItem
        {...shared}
        date={ago(40)}
        marker={
          <Avatar name="Lucía Ortega" src="https://i.pravatar.cc/96?u=lucia" />
        }
        heading={
          <>
            <strong>Lucía Ortega</strong> commented
          </>
        }
      >
        <Card size="sm" border="default">
          The 600 step fails AA on the dark page by a hair. Nudging lightness by
          two points fixes it without touching the hue.
        </Card>
      </TimelineItem>
      <TimelineItem
        {...shared}
        date={ago(95)}
        marker={
          <Stamp tone="primary" shape="circle">
            <svg
              xmlns="http://www.w3.org/2000/svg"
              width="24"
              height="24"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              stroke-width="2"
              stroke-linecap="round"
              stroke-linejoin="round"
              class="lucide lucide-git-pull-request"
              aria-hidden="true"
            >
              <circle cx="18" cy="18" r="3" />
              <circle cx="6" cy="6" r="3" />
              <path d="M13 6h3a2 2 0 0 1 2 2v7" />
              <line x1="6" x2="6" y1="9" y2="21" />
            </svg>
          </Stamp>
        }
        heading={
          <>
            <strong>Kenji Mori</strong> asked to merge{" "}
            <strong>tokens/danger-600</strong>
          </>
        }
        actions={
          <>
            <Button size="sm" emphasis="secondary">
              Decline
            </Button>
            <Button size="sm" emphasis="primary">
              Approve
            </Button>
          </>
        }
      />
      <TimelineCollapse count={3}>
        <TimelineItem
          {...shared}
          date={ago(130)}
          heading={
            <>
              <strong>Kenji Mori</strong> pushed 2 commits
            </>
          }
        />
        <TimelineItem
          {...shared}
          date={ago(160)}
          marker={
            <Stamp emphasis="ghost" shape="circle">
              <svg
                xmlns="http://www.w3.org/2000/svg"
                width="24"
                height="24"
                viewBox="0 0 24 24"
                fill="none"
                stroke="currentColor"
                stroke-width="2"
                stroke-linecap="round"
                stroke-linejoin="round"
                class="lucide lucide-tag"
                aria-hidden="true"
              >
                <path d="M12.586 2.586A2 2 0 0 0 11.172 2H4a2 2 0 0 0-2 2v7.172a2 2 0 0 0 .586 1.414l8.704 8.704a2.426 2.426 0 0 0 3.42 0l6.58-6.58a2.426 2.426 0 0 0 0-3.42z" />
                <circle cx="7.5" cy="7.5" r=".5" fill="currentColor" />
              </svg>
            </Stamp>
          }
          heading={
            <>
              <strong>Marta Silva</strong> added the <strong>color</strong>{" "}
              label
            </>
          }
        />
        <TimelineItem
          {...shared}
          date={ago(200)}
          heading={
            <>
              <strong>Marta Silva</strong> opened the issue
            </>
          }
        />
      </TimelineCollapse>
      <TimelineSeparator label="Last week" />
      <TimelineItem
        {...shared}
        date={ago(60 * 24 * 6)}
        tone="success"
        marker={
          <Stamp tone="success" shape="circle">
            <svg
              xmlns="http://www.w3.org/2000/svg"
              width="24"
              height="24"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              stroke-width="2"
              stroke-linecap="round"
              stroke-linejoin="round"
              class="lucide lucide-circle-check"
              aria-hidden="true"
            >
              <circle cx="12" cy="12" r="10" />
              <path d="m16 9-5.5 5.5L8 12" />
            </svg>
          </Stamp>
        }
        heading={
          <>
            Checks passed on <strong>main</strong>
          </>
        }
      />
    </Timeline>
  );
}

Header tiers

Each part of an entry gets its own tier, so the date never competes with the title. The header is a Banner:

eyebrow: an optional kicker above the heading: a time, an id, a pipeline stage. The marker stays centred on the heading line, not on the kicker.
heading: title, or the heading slot for rich content.
meta: the formatted date, or the meta slot. Where it sits depends on metaPlacement:
- below (default): its own muted line under the heading.
- above: the kicker above the heading, after the eyebrow when there is one. Use it for schedules, where the time leads.
- inline: after the heading on the same line, for dense logs such as an audit trail.

passThrough.header, heading, eyebrow and meta style each tier. They are applied to the Banner’s rows, so they follow the meta wherever metaPlacement puts it.

Comments and threads

A comment is an entry with an avatar marker, the author as title, a relative date and the text as its body. For replies, nest a Timeline in the body. A nested timeline with no size of its own drops to sm, so the thread reads as subordinate to its parent. Collapse long threads with TimelineCollapse and a custom labels.more.

PreviewCode

Priya Nair

3 hours ago

Should the compact density ship in this release, or wait until the table supports it too?

Tomás Reyes

2 hours ago

Wait. Half a density story is worse than none.

Ines Duarte

30 minutes ago

Agreed. Moving it to the next milestone.

Ines Duarte

10 minutes ago

Release notes draft is up — tone welcome before Friday.

---
// GENERATED from packages/demos/timeline/comments.demo.tsx — edit the source, not this file.
import {
  Timeline,
  TimelineCollapse,
  TimelineItem,
} from "@pindoba/astro-timeline";
import Avatar from "@pindoba/astro-avatar";
import Button from "@pindoba/astro-button";
import Stamp from "@pindoba/astro-stamp";
import { Reply, Heart } from "@lucide/astro";

const NOW = new Date(2026, 9, 16, 15, 0);
const ago = (minutes: number) => new Date(NOW.getTime() - minutes * 60_000);
const shared = { now: NOW, locale: "en-US", dateFormat: "relative" } as const;
---

<Timeline line="none">
  <TimelineItem {...shared} title="Priya Nair" date={ago(180)}>
    <Avatar
      slot="marker"
      name="Priya Nair"
      src="https://i.pravatar.cc/96?u=priya"
    />
    Should the compact density ship in this release, or wait until the table
    supports it too?
    <Timeline>
      <TimelineItem {...shared} title="Tomás Reyes" date={ago(150)}>
        <Avatar slot="marker" name="Tomás Reyes" />
        Wait. Half a density story is worse than none.
      </TimelineItem>
      <TimelineCollapse
        count={2}
        labels={{ more: (n: number | undefined) => `${n} more replies` }}
      >
        <TimelineItem {...shared} title="Priya Nair" date={ago(120)}>
          <Avatar
            slot="marker"
            name="Priya Nair"
            src="https://i.pravatar.cc/96?u=priya"
          />
          Fair. The table work is two weeks out.
        </TimelineItem>
        <TimelineItem {...shared} title="Tomás Reyes" date={ago(90)}>
          <Avatar slot="marker" name="Tomás Reyes" />I can pair on it next
          sprint.
        </TimelineItem>
      </TimelineCollapse>
      <TimelineItem {...shared} title="Ines Duarte" date={ago(30)}>
        <Avatar slot="marker" name="Ines Duarte" />
        <Fragment slot="actions">
          <Button size="xs" emphasis="ghost">
            <Stamp slot="leading" emphasis="ghost">
              <Reply />
            </Stamp>
            Reply
          </Button>
          <Button size="xs" emphasis="ghost" aria-label="Like">
            <Stamp slot="leading" emphasis="ghost">
              <Heart />
            </Stamp>
          </Button>
        </Fragment>
        Agreed. Moving it to the next milestone.
      </TimelineItem>
    </Timeline>
  </TimelineItem>
  <TimelineItem {...shared} title="Ines Duarte" date={ago(10)}>
    <Avatar slot="marker" name="Ines Duarte" />
    <Fragment slot="actions">
      <Button size="xs" emphasis="ghost">
        <Stamp slot="leading" emphasis="ghost">
          <Reply />
        </Stamp>
        Reply
      </Button>
      <Button size="xs" emphasis="ghost" aria-label="Like">
        <Stamp slot="leading" emphasis="ghost">
          <Heart />
        </Stamp>
      </Button>
    </Fragment>
    Release notes draft is up — tone welcome before Friday.
  </TimelineItem>
</Timeline>

Priya Nair

3 hours ago

Should the compact density ship in this release, or wait until the table supports it too?

Tomás Reyes

2 hours ago

Wait. Half a density story is worse than none.

Ines Duarte

30 minutes ago

Agreed. Moving it to the next milestone.

Ines Duarte

10 minutes ago

Release notes draft is up — tone welcome before Friday.

<script lang="ts">
  // GENERATED from packages/demos/timeline/comments.demo.tsx — edit the source, not this file.
  import Timeline from "@pindoba/svelte-timeline";
  import { TimelineCollapse, TimelineItem } from "@pindoba/svelte-timeline";
  import Avatar from "@pindoba/svelte-avatar";
  import Button from "@pindoba/svelte-button";
  import Stamp from "@pindoba/svelte-stamp";
  import LucideReply from "@lucide/svelte/icons/reply";
  import LucideHeart from "@lucide/svelte/icons/heart";

  const NOW = new Date(2026, 9, 16, 15, 0);
  const ago = (minutes: number) => new Date(NOW.getTime() - minutes * 60_000);
  const shared = { now: NOW, locale: "en-US", dateFormat: "relative" } as const;
</script>

{#snippet reactions()}
  <Button size="xs" emphasis="ghost">
    {#snippet leading()}
      <Stamp emphasis="ghost">
        <LucideReply />
      </Stamp>
    {/snippet}
    Reply
  </Button>
  <Button size="xs" emphasis="ghost" aria-label="Like">
    {#snippet leading()}
      <Stamp emphasis="ghost">
        <LucideHeart />
      </Stamp>
    {/snippet}
  </Button>
{/snippet}

<Timeline line="none">
  <TimelineItem {...shared} title="Priya Nair" date={ago(180)}>
    {#snippet marker()}
      <Avatar name="Priya Nair" src="https://i.pravatar.cc/96?u=priya"></Avatar>
    {/snippet}
    Should the compact density ship in this release, or wait until the table supports
    it too?<Timeline>
      <TimelineItem {...shared} title="Tomás Reyes" date={ago(150)}>
        {#snippet marker()}
          <Avatar name="Tomás Reyes"></Avatar>
        {/snippet}
        Wait. Half a density story is worse than none.
      </TimelineItem>
      <TimelineCollapse
        count={2}
        labels={{ more: (n: number | undefined) => `${n} more replies` }}
      >
        <TimelineItem {...shared} title="Priya Nair" date={ago(120)}>
          {#snippet marker()}
            <Avatar name="Priya Nair" src="https://i.pravatar.cc/96?u=priya"
            ></Avatar>
          {/snippet}
          Fair. The table work is two weeks out.
        </TimelineItem>
        <TimelineItem {...shared} title="Tomás Reyes" date={ago(90)}>
          {#snippet marker()}
            <Avatar name="Tomás Reyes"></Avatar>
          {/snippet}
          I can pair on it next sprint.
        </TimelineItem>
      </TimelineCollapse>
      <TimelineItem {...shared} title="Ines Duarte" date={ago(30)}>
        {#snippet marker()}
          <Avatar name="Ines Duarte"></Avatar>
        {/snippet}
        {#snippet actions()}
          {@render reactions()}
        {/snippet}
        Agreed. Moving it to the next milestone.
      </TimelineItem>
    </Timeline>
  </TimelineItem>
  <TimelineItem {...shared} title="Ines Duarte" date={ago(10)}>
    {#snippet marker()}
      <Avatar name="Ines Duarte"></Avatar>
    {/snippet}
    {#snippet actions()}
      {@render reactions()}
    {/snippet}
    Release notes draft is up — tone welcome before Friday.
  </TimelineItem>
</Timeline>

Priya Nair

3 hours ago

Should the compact density ship in this release, or wait until the table supports it too?

Tomás Reyes

2 hours ago

Wait. Half a density story is worse than none.

Ines Duarte

30 minutes ago

Agreed. Moving it to the next milestone.

Ines Duarte

10 minutes ago

Release notes draft is up — tone welcome before Friday.

// GENERATED from packages/demos/timeline/comments.demo.tsx — edit the source, not this file.
import {
  Timeline,
  TimelineCollapse,
  TimelineItem,
} from "@pindoba/solid-timeline";
import { Avatar } from "@pindoba/solid-avatar";
import { Button } from "@pindoba/solid-button";
import { Stamp } from "@pindoba/solid-stamp";

const NOW = new Date(2026, 9, 16, 15, 0);
const ago = (minutes: number) => new Date(NOW.getTime() - minutes * 60_000);
const shared = { now: NOW, locale: "en-US", dateFormat: "relative" } as const;
export default function CommentsDemo() {
  const reactions = () => (
    <>
      <Button
        size="xs"
        emphasis="ghost"
        leading={
          <Stamp emphasis="ghost">
            <svg
              xmlns="http://www.w3.org/2000/svg"
              width="24"
              height="24"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              stroke-width="2"
              stroke-linecap="round"
              stroke-linejoin="round"
              class="lucide lucide-reply"
              aria-hidden="true"
            >
              <path d="M20 18v-2a4 4 0 0 0-4-4H4" />
              <path d="m9 17-5-5 5-5" />
            </svg>
          </Stamp>
        }
      >
        Reply
      </Button>
      <Button
        size="xs"
        emphasis="ghost"
        aria-label="Like"
        leading={
          <Stamp emphasis="ghost">
            <svg
              xmlns="http://www.w3.org/2000/svg"
              width="24"
              height="24"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              stroke-width="2"
              stroke-linecap="round"
              stroke-linejoin="round"
              class="lucide lucide-heart"
              aria-hidden="true"
            >
              <path d="M2 9.5a5.5 5.5 0 0 1 9.591-3.676.56.56 0 0 0 .818 0A5.49 5.49 0 0 1 22 9.5c0 2.29-1.5 4-3 5.5l-5.492 5.313a2 2 0 0 1-3 .019L5 15c-1.5-1.5-3-3.2-3-5.5" />
            </svg>
          </Stamp>
        }
      />
    </>
  );

  return (
    <Timeline line="none">
      <TimelineItem
        {...shared}
        title="Priya Nair"
        date={ago(180)}
        marker={
          <Avatar name="Priya Nair" src="https://i.pravatar.cc/96?u=priya" />
        }
      >
        Should the compact density ship in this release, or wait until the table
        supports it too?
        <Timeline>
          <TimelineItem
            {...shared}
            title="Tomás Reyes"
            date={ago(150)}
            marker={<Avatar name="Tomás Reyes" />}
          >
            Wait. Half a density story is worse than none.
          </TimelineItem>
          <TimelineCollapse
            count={2}
            labels={{ more: (n: number | undefined) => `${n} more replies` }}
          >
            <TimelineItem
              {...shared}
              title="Priya Nair"
              date={ago(120)}
              marker={
                <Avatar
                  name="Priya Nair"
                  src="https://i.pravatar.cc/96?u=priya"
                />
              }
            >
              Fair. The table work is two weeks out.
            </TimelineItem>
            <TimelineItem
              {...shared}
              title="Tomás Reyes"
              date={ago(90)}
              marker={<Avatar name="Tomás Reyes" />}
            >
              I can pair on it next sprint.
            </TimelineItem>
          </TimelineCollapse>
          <TimelineItem
            {...shared}
            title="Ines Duarte"
            date={ago(30)}
            marker={<Avatar name="Ines Duarte" />}
            actions={reactions()}
          >
            Agreed. Moving it to the next milestone.
          </TimelineItem>
        </Timeline>
      </TimelineItem>
      <TimelineItem
        {...shared}
        title="Ines Duarte"
        date={ago(10)}
        marker={<Avatar name="Ines Duarte" />}
        actions={reactions()}
      >
        Release notes draft is up — tone welcome before Friday.
      </TimelineItem>
    </Timeline>
  );
}

Collapsing entries

TimelineCollapse renders a toggle row on the rail, followed by its children: real TimelineItems in a region that is hidden until expanded. Both wrappers are display: contents with role="none", so once shown, the entries are ordinary list items and the rail runs through them unbroken.

The toggle is a Button with aria-expanded and aria-controls pointing at the region.
count feeds the default “Show N more” text. labels takes { more, less }, and more can be a function of the count.
In Svelte, expanded is bindable. In Astro, a small script from @pindoba/core-timeline/runtime toggles it. It needs no framework and re-binds after View Transitions.

Markers

Marker slot	Renders
empty	a dot in the item’s `tone` colour (`neutral` by default)
a `Stamp` or `Avatar`	that component, sized to the rail
empty, with `state` set	a state stamp (see Step states)
`hideMarker`	nothing; the line runs straight through

bleed lets an entry’s content span the rail too: a full-width card that interrupts the line.

PreviewCode

Neutral

A plain dot — the default for activity entries.

Primary

Version 2.4 was released.

Note

The changelog was updated.

Success

The pipeline passed.

Warning

Bundle size grew by 40kb.

Danger

A hardcoded secret was found.

---
// GENERATED from packages/demos/timeline/tone.demo.tsx — edit the source, not this file.
import Stamp from "@pindoba/astro-stamp";
import { Timeline, TimelineItem } from "@pindoba/astro-timeline";
import {
  Rocket,
  Info,
  CircleCheck,
  TriangleAlert,
  ShieldAlert,
} from "@lucide/astro";
---

<Timeline>
  <TimelineItem tone="neutral" title="Neutral">
    A plain dot — the default for activity entries.
  </TimelineItem>
  <TimelineItem tone="primary" title="Primary">
    <Stamp slot="marker" tone="primary" shape="circle">
      <Rocket />
    </Stamp>
    Version 2.4 was released.
  </TimelineItem>
  <TimelineItem tone="neutral" title="Note">
    <Stamp slot="marker" emphasis="tertiary" shape="circle">
      <Info />
    </Stamp>
    The changelog was updated.
  </TimelineItem>
  <TimelineItem tone="success" title="Success">
    <Stamp slot="marker" tone="success" shape="circle">
      <CircleCheck />
    </Stamp>
    The pipeline passed.
  </TimelineItem>
  <TimelineItem tone="warning" title="Warning">
    <Stamp slot="marker" tone="warning" shape="circle">
      <TriangleAlert />
    </Stamp>
    Bundle size grew by 40kb.
  </TimelineItem>
  <TimelineItem tone="danger" title="Danger">
    <Stamp slot="marker" tone="danger" emphasis="primary" shape="circle">
      <ShieldAlert />
    </Stamp>
    A hardcoded secret was found.
  </TimelineItem>
</Timeline>

Neutral

A plain dot — the default for activity entries.

Primary

Version 2.4 was released.

Note

The changelog was updated.

Success

The pipeline passed.

Warning

Bundle size grew by 40kb.

Danger

A hardcoded secret was found.

// GENERATED from packages/demos/timeline/tone.demo.tsx — edit the source, not this file.
import { Stamp } from "@pindoba/react-stamp";
import { Timeline, TimelineItem } from "@pindoba/react-timeline";
import { Rocket } from "lucide-react";
import { Info } from "lucide-react";
import { CircleCheck } from "lucide-react";
import { TriangleAlert } from "lucide-react";
import { ShieldAlert } from "lucide-react";

export default function ToneDemo() {
  return (
    <Timeline>
      <TimelineItem tone="neutral" title="Neutral">
        A plain dot — the default for activity entries.
      </TimelineItem>
      <TimelineItem
        tone="primary"
        title="Primary"
        marker={
          <Stamp tone="primary" shape="circle">
            <Rocket />
          </Stamp>
        }
      >
        Version 2.4 was released.
      </TimelineItem>
      <TimelineItem
        tone="neutral"
        title="Note"
        marker={
          <Stamp emphasis="tertiary" shape="circle">
            <Info />
          </Stamp>
        }
      >
        The changelog was updated.
      </TimelineItem>
      <TimelineItem
        tone="success"
        title="Success"
        marker={
          <Stamp tone="success" shape="circle">
            <CircleCheck />
          </Stamp>
        }
      >
        The pipeline passed.
      </TimelineItem>
      <TimelineItem
        tone="warning"
        title="Warning"
        marker={
          <Stamp tone="warning" shape="circle">
            <TriangleAlert />
          </Stamp>
        }
      >
        Bundle size grew by 40kb.
      </TimelineItem>
      <TimelineItem
        tone="danger"
        title="Danger"
        marker={
          <Stamp tone="danger" emphasis="primary" shape="circle">
            <ShieldAlert />
          </Stamp>
        }
      >
        A hardcoded secret was found.
      </TimelineItem>
    </Timeline>
  );
}

Neutral

A plain dot — the default for activity entries.

Primary

Version 2.4 was released.

Note

The changelog was updated.

Success

The pipeline passed.

Warning

Bundle size grew by 40kb.

Danger

A hardcoded secret was found.

<script lang="ts">
  // GENERATED from packages/demos/timeline/tone.demo.tsx — edit the source, not this file.
  import Stamp from "@pindoba/svelte-stamp";
  import Timeline from "@pindoba/svelte-timeline";
  import { TimelineItem } from "@pindoba/svelte-timeline";
  import LucideRocket from "@lucide/svelte/icons/rocket";
  import LucideInfo from "@lucide/svelte/icons/info";
  import LucideCircleCheck from "@lucide/svelte/icons/circle-check";
  import LucideTriangleAlert from "@lucide/svelte/icons/triangle-alert";
  import LucideShieldAlert from "@lucide/svelte/icons/shield-alert";
</script>

<Timeline>
  <TimelineItem tone="neutral" title="Neutral">
    A plain dot — the default for activity entries.
  </TimelineItem>
  <TimelineItem tone="primary" title="Primary">
    {#snippet marker()}
      <Stamp tone="primary" shape="circle">
        <LucideRocket />
      </Stamp>
    {/snippet}
    Version 2.4 was released.
  </TimelineItem>
  <TimelineItem tone="neutral" title="Note">
    {#snippet marker()}
      <Stamp emphasis="tertiary" shape="circle">
        <LucideInfo />
      </Stamp>
    {/snippet}
    The changelog was updated.
  </TimelineItem>
  <TimelineItem tone="success" title="Success">
    {#snippet marker()}
      <Stamp tone="success" shape="circle">
        <LucideCircleCheck />
      </Stamp>
    {/snippet}
    The pipeline passed.
  </TimelineItem>
  <TimelineItem tone="warning" title="Warning">
    {#snippet marker()}
      <Stamp tone="warning" shape="circle">
        <LucideTriangleAlert />
      </Stamp>
    {/snippet}
    Bundle size grew by 40kb.
  </TimelineItem>
  <TimelineItem tone="danger" title="Danger">
    {#snippet marker()}
      <Stamp tone="danger" emphasis="primary" shape="circle">
        <LucideShieldAlert />
      </Stamp>
    {/snippet}
    A hardcoded secret was found.
  </TimelineItem>
</Timeline>

Neutral

A plain dot — the default for activity entries.

Primary

Version 2.4 was released.

Note

The changelog was updated.

Success

The pipeline passed.

Warning

Bundle size grew by 40kb.

Danger

A hardcoded secret was found.

<script setup lang="ts">
// GENERATED from packages/demos/timeline/tone.demo.tsx — edit the source, not this file.
import { Stamp } from "@pindoba/vue-stamp";
import { Timeline, TimelineItem } from "@pindoba/vue-timeline";
</script>

<template>
  <Timeline>
    <TimelineItem tone="neutral" title="Neutral"
      >A plain dot — the default for activity entries.</TimelineItem
    >
    <TimelineItem tone="primary" title="Primary">
      <template #marker>
        <Stamp tone="primary" shape="circle">
          <svg
            xmlns="http://www.w3.org/2000/svg"
            width="24"
            height="24"
            viewBox="0 0 24 24"
            fill="none"
            stroke="currentColor"
            stroke-width="2"
            stroke-linecap="round"
            stroke-linejoin="round"
            class="lucide lucide-rocket"
            aria-hidden="true"
          >
            <path d="M12 15v5s3.03-.55 4-2c1.08-1.62 0-5 0-5" />
            <path
              d="M4.5 16.5c-1.5 1.26-2 5-2 5s3.74-.5 5-2c.71-.84.7-2.13-.09-2.91a2.18 2.18 0 0 0-2.91-.09"
            />
            <path
              d="M9 12a22 22 0 0 1 2-3.95A12.88 12.88 0 0 1 22 2c0 2.72-.78 7.5-6 11a22.4 22.4 0 0 1-4 2z"
            />
            <path d="M9 12H4s.55-3.03 2-4c1.62-1.08 5 .05 5 .05" />
          </svg>
        </Stamp>
      </template>
      Version 2.4 was released.
    </TimelineItem>
    <TimelineItem tone="neutral" title="Note">
      <template #marker>
        <Stamp emphasis="tertiary" shape="circle">
          <svg
            xmlns="http://www.w3.org/2000/svg"
            width="24"
            height="24"
            viewBox="0 0 24 24"
            fill="none"
            stroke="currentColor"
            stroke-width="2"
            stroke-linecap="round"
            stroke-linejoin="round"
            class="lucide lucide-info"
            aria-hidden="true"
          >
            <circle cx="12" cy="12" r="10" />
            <path d="M12 16v-4" />
            <path d="M12 8h.01" />
          </svg>
        </Stamp>
      </template>
      The changelog was updated.
    </TimelineItem>
    <TimelineItem tone="success" title="Success">
      <template #marker>
        <Stamp tone="success" shape="circle">
          <svg
            xmlns="http://www.w3.org/2000/svg"
            width="24"
            height="24"
            viewBox="0 0 24 24"
            fill="none"
            stroke="currentColor"
            stroke-width="2"
            stroke-linecap="round"
            stroke-linejoin="round"
            class="lucide lucide-circle-check"
            aria-hidden="true"
          >
            <circle cx="12" cy="12" r="10" />
            <path d="m16 9-5.5 5.5L8 12" />
          </svg>
        </Stamp>
      </template>
      The pipeline passed.
    </TimelineItem>
    <TimelineItem tone="warning" title="Warning">
      <template #marker>
        <Stamp tone="warning" shape="circle">
          <svg
            xmlns="http://www.w3.org/2000/svg"
            width="24"
            height="24"
            viewBox="0 0 24 24"
            fill="none"
            stroke="currentColor"
            stroke-width="2"
            stroke-linecap="round"
            stroke-linejoin="round"
            class="lucide lucide-triangle-alert"
            aria-hidden="true"
          >
            <path
              d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"
            />
            <path d="M12 9v4" />
            <path d="M12 17h.01" />
          </svg>
        </Stamp>
      </template>
      Bundle size grew by 40kb.
    </TimelineItem>
    <TimelineItem tone="danger" title="Danger">
      <template #marker>
        <Stamp tone="danger" emphasis="primary" shape="circle">
          <svg
            xmlns="http://www.w3.org/2000/svg"
            width="24"
            height="24"
            viewBox="0 0 24 24"
            fill="none"
            stroke="currentColor"
            stroke-width="2"
            stroke-linecap="round"
            stroke-linejoin="round"
            class="lucide lucide-shield-alert"
            aria-hidden="true"
          >
            <path
              d="M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z"
            />
            <path d="M12 8v4" />
            <path d="M12 16h.01" />
          </svg>
        </Stamp>
      </template>
      A hardcoded secret was found.
    </TimelineItem>
  </Timeline>
</template>

Neutral

A plain dot — the default for activity entries.

Primary

Version 2.4 was released.

Note

The changelog was updated.

Success

The pipeline passed.

Warning

Bundle size grew by 40kb.

Danger

A hardcoded secret was found.

// GENERATED from packages/demos/timeline/tone.demo.tsx — edit the source, not this file.
import { Stamp } from "@pindoba/solid-stamp";
import { Timeline, TimelineItem } from "@pindoba/solid-timeline";

export default function ToneDemo() {
  return (
    <Timeline>
      <TimelineItem tone="neutral" title="Neutral">
        A plain dot — the default for activity entries.
      </TimelineItem>
      <TimelineItem
        tone="primary"
        title="Primary"
        marker={
          <Stamp tone="primary" shape="circle">
            <svg
              xmlns="http://www.w3.org/2000/svg"
              width="24"
              height="24"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              stroke-width="2"
              stroke-linecap="round"
              stroke-linejoin="round"
              class="lucide lucide-rocket"
              aria-hidden="true"
            >
              <path d="M12 15v5s3.03-.55 4-2c1.08-1.62 0-5 0-5" />
              <path d="M4.5 16.5c-1.5 1.26-2 5-2 5s3.74-.5 5-2c.71-.84.7-2.13-.09-2.91a2.18 2.18 0 0 0-2.91-.09" />
              <path d="M9 12a22 22 0 0 1 2-3.95A12.88 12.88 0 0 1 22 2c0 2.72-.78 7.5-6 11a22.4 22.4 0 0 1-4 2z" />
              <path d="M9 12H4s.55-3.03 2-4c1.62-1.08 5 .05 5 .05" />
            </svg>
          </Stamp>
        }
      >
        Version 2.4 was released.
      </TimelineItem>
      <TimelineItem
        tone="neutral"
        title="Note"
        marker={
          <Stamp emphasis="tertiary" shape="circle">
            <svg
              xmlns="http://www.w3.org/2000/svg"
              width="24"
              height="24"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              stroke-width="2"
              stroke-linecap="round"
              stroke-linejoin="round"
              class="lucide lucide-info"
              aria-hidden="true"
            >
              <circle cx="12" cy="12" r="10" />
              <path d="M12 16v-4" />
              <path d="M12 8h.01" />
            </svg>
          </Stamp>
        }
      >
        The changelog was updated.
      </TimelineItem>
      <TimelineItem
        tone="success"
        title="Success"
        marker={
          <Stamp tone="success" shape="circle">
            <svg
              xmlns="http://www.w3.org/2000/svg"
              width="24"
              height="24"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              stroke-width="2"
              stroke-linecap="round"
              stroke-linejoin="round"
              class="lucide lucide-circle-check"
              aria-hidden="true"
            >
              <circle cx="12" cy="12" r="10" />
              <path d="m16 9-5.5 5.5L8 12" />
            </svg>
          </Stamp>
        }
      >
        The pipeline passed.
      </TimelineItem>
      <TimelineItem
        tone="warning"
        title="Warning"
        marker={
          <Stamp tone="warning" shape="circle">
            <svg
              xmlns="http://www.w3.org/2000/svg"
              width="24"
              height="24"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              stroke-width="2"
              stroke-linecap="round"
              stroke-linejoin="round"
              class="lucide lucide-triangle-alert"
              aria-hidden="true"
            >
              <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" />
              <path d="M12 9v4" />
              <path d="M12 17h.01" />
            </svg>
          </Stamp>
        }
      >
        Bundle size grew by 40kb.
      </TimelineItem>
      <TimelineItem
        tone="danger"
        title="Danger"
        marker={
          <Stamp tone="danger" emphasis="primary" shape="circle">
            <svg
              xmlns="http://www.w3.org/2000/svg"
              width="24"
              height="24"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              stroke-width="2"
              stroke-linecap="round"
              stroke-linejoin="round"
              class="lucide lucide-shield-alert"
              aria-hidden="true"
            >
              <path d="M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z" />
              <path d="M12 8v4" />
              <path d="M12 16h.01" />
            </svg>
          </Stamp>
        }
      >
        A hardcoded secret was found.
      </TimelineItem>
    </Timeline>
  );
}

Sizes and lines

size sets every rail measurement at once: the marker box, dot, line width, spacing and text size. The marker box follows the control scale, so a marker lines up with buttons of the same size.

sm for dense logs
md (the default) for general use
lg for roomy step trackers

line draws the connector solid (the default), dashed or none. With none the marker column stays, so markers still align.

PreviewCode

size="sm"

line="solid"

Completed

In review

Current step

Released

Not started

size="md"

line="dashed"

Completed

In review

Current step

Released

Not started

size="lg"

line="none"

Completed

In review

Current step

Released

Not started

---
// GENERATED from packages/demos/timeline/sizes.demo.tsx — edit the source, not this file.
import { Timeline, TimelineItem } from "@pindoba/astro-timeline";
import { css } from "@pindoba/styled-system/css";

const variants = [
  { size: "sm", line: "solid" },
  { size: "md", line: "dashed" },
  { size: "lg", line: "none" },
] as const;
---

<div
  class={css({
    display: "grid",
    gridTemplateColumns: "repeat(auto-fit, minmax(200px, 1fr))",
    gap: "xl",
  })}
>
  {variants.map((v) => (
    <Timeline size={v.size} line={v.line}>
      <TimelineItem title={`size="${v.size}"`} />
      <TimelineItem state="done" title={`line="${v.line}"`} />
      <TimelineItem state="current" title="In review" />
      <TimelineItem state="upcoming" title="Released" />
    </Timeline>
  ))}
</div>

size="sm"

line="solid"

Completed

In review

Current step

Released

Not started

size="md"

line="dashed"

Completed

In review

Current step

Released

Not started

size="lg"

line="none"

Completed

In review

Current step

Released

Not started

// GENERATED from packages/demos/timeline/sizes.demo.tsx — edit the source, not this file.
import { Timeline, TimelineItem } from "@pindoba/react-timeline";
import { css } from "@pindoba/styled-system/css";

const variants = [
  { size: "sm", line: "solid" },
  { size: "md", line: "dashed" },
  { size: "lg", line: "none" },
] as const;
export default function SizesDemo() {
  return (
    <div
      className={css({
        display: "grid",
        gridTemplateColumns: "repeat(auto-fit, minmax(200px, 1fr))",
        gap: "xl",
      })}
    >
      {variants.map((v) => (
        <Timeline key={v.size} size={v.size} line={v.line}>
          <TimelineItem title={`size="${v.size}"`} />
          <TimelineItem state="done" title={`line="${v.line}"`} />
          <TimelineItem state="current" title="In review" />
          <TimelineItem state="upcoming" title="Released" />
        </Timeline>
      ))}
    </div>
  );
}

size="sm"

line="solid"

Completed

In review

Current step

Released

Not started

size="md"

line="dashed"

Completed

In review

Current step

Released

Not started

size="lg"

line="none"

Completed

In review

Current step

Released

Not started

<script lang="ts">
  // GENERATED from packages/demos/timeline/sizes.demo.tsx — edit the source, not this file.
  import Timeline from "@pindoba/svelte-timeline";
  import { TimelineItem } from "@pindoba/svelte-timeline";
  import { css } from "@pindoba/styled-system/css";

  const variants = [
    { size: "sm", line: "solid" },
    { size: "md", line: "dashed" },
    { size: "lg", line: "none" },
  ] as const;
</script>

<div
  class={css({
    display: "grid",
    gridTemplateColumns: "repeat(auto-fit, minmax(200px, 1fr))",
    gap: "xl",
  })}
>
  {#each variants as v (v.size)}
    <Timeline size={v.size} line={v.line}>
      <TimelineItem title={`size="${v.size}"`}></TimelineItem>
      <TimelineItem state="done" title={`line="${v.line}"`}></TimelineItem>
      <TimelineItem state="current" title="In review"></TimelineItem>
      <TimelineItem state="upcoming" title="Released"></TimelineItem>
    </Timeline>
  {/each}
</div>

size="sm"

line="solid"

Completed

In review

Current step

Released

Not started

size="md"

line="dashed"

Completed

In review

Current step

Released

Not started

size="lg"

line="none"

Completed

In review

Current step

Released

Not started

<script setup lang="ts">
// GENERATED from packages/demos/timeline/sizes.demo.tsx — edit the source, not this file.
import { Timeline, TimelineItem } from "@pindoba/vue-timeline";
import { css } from "@pindoba/styled-system/css";

const variants = [
  { size: "sm", line: "solid" },
  { size: "md", line: "dashed" },
  { size: "lg", line: "none" },
] as const;
</script>

<template>
  <div
    :class="
      css({
        display: 'grid',
        gridTemplateColumns: 'repeat(auto-fit, minmax(200px, 1fr))',
        gap: 'xl',
      })
    "
  >
    <Timeline v-for="v in variants" :key="v.size" :size="v.size" :line="v.line">
      <TimelineItem :title="`size=&quot;${v.size}&quot;`"></TimelineItem>
      <TimelineItem
        state="done"
        :title="`line=&quot;${v.line}&quot;`"
      ></TimelineItem>
      <TimelineItem state="current" title="In review"></TimelineItem>
      <TimelineItem state="upcoming" title="Released"></TimelineItem>
    </Timeline>
  </div>
</template>

size="sm"

line="solid"

Completed

In review

Current step

Released

Not started

size="md"

line="dashed"

Completed

In review

Current step

Released

Not started

size="lg"

line="none"

Completed

In review

Current step

Released

Not started

// GENERATED from packages/demos/timeline/sizes.demo.tsx — edit the source, not this file.
import { For } from "solid-js";
import { Timeline, TimelineItem } from "@pindoba/solid-timeline";
import { css } from "@pindoba/styled-system/css";

const variants = [
  { size: "sm", line: "solid" },
  { size: "md", line: "dashed" },
  { size: "lg", line: "none" },
] as const;
export default function SizesDemo() {
  return (
    <div
      class={css({
        display: "grid",
        gridTemplateColumns: "repeat(auto-fit, minmax(200px, 1fr))",
        gap: "xl",
      })}
    >
      <For each={variants}>
        {(v) => (
          <Timeline size={v.size} line={v.line}>
            <TimelineItem title={`size="${v.size}"`} />
            <TimelineItem state="done" title={`line="${v.line}"`} />
            <TimelineItem state="current" title="In review" />
            <TimelineItem state="upcoming" title="Released" />
          </Timeline>
        )}
      </For>
    </div>
  );
}

Dates

date takes a single Date or a [start, end] range and renders in the meta line. Formatting lives in core, so every framework prints the same string:

A range that ends today and is still running reads as ”… - now”. A date-only end runs through today; an end with a time reads “now” only while the range is running, so a meeting that ended this morning stays a plain range.
Malformed input degrades to Invalid date rather than throwing mid-render.
locale formats for a specific BCP 47 locale. It defaults to the runtime’s.

How dates are written:

Default: the day only ({ dateStyle: "long" }).
dateFormat: "relative": “3 days ago” or “yesterday”, in the largest whole unit. The absolute date goes in the element’s title. Relative text does not update on its own, so re-render to refresh it. Pass now to pin the reference instant, which keeps server and client output identical.
dateFormat with Intl.DateTimeFormat options: for example { dateStyle: "long", timeStyle: "short" } to add the time. An invalid combination falls back to the default.
formatDate: a (date, locale) => string function. It wins over dateFormat.

Each date is a machine-readable <time datetime="…">:

datetime is date-only (2026-01-05) for a Date at local midnight.
It is the full ISO instant otherwise, or when dateFormat.timeZone is set.
The “now” end of a range is plain text: it names no fixed day.

passThrough.time styles every <time>. The meta slot replaces the date line entirely. Several elements in it (a link, a count, a time) are joined with a ”·”.

PreviewCode

January 5, 2026

A date on its own fills the header.

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".

With the time

March 9, 2026 at 2:30 PM

dateFormat takes Intl.DateTimeFormat options.

Relative

3 days ago

Hover the time for the absolute date.

---
// GENERATED from packages/demos/timeline/dates.demo.tsx — edit the source, not this file.
import { Timeline, TimelineItem } from "@pindoba/astro-timeline";

const START = new Date(2026, 0, 5);
const END = new Date(2026, 2, 9);
const DEPLOYED = new Date(2026, 2, 9, 14, 30);
const NOW = new Date(2026, 2, 12, 9, 0);
---

<Timeline>
  <TimelineItem date={START} locale="en-US">
    A date on its own fills the header.
  </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>
  <TimelineItem
    title="With the time"
    date={DEPLOYED}
    locale="en-US"
    dateFormat={{
      year: "numeric",
      month: "long",
      day: "numeric",
      hour: "numeric",
      minute: "2-digit",
    }}
  >
    <code>dateFormat</code> takes <code>Intl.DateTimeFormat</code> options.
  </TimelineItem>
  <TimelineItem
    title="Relative"
    date={DEPLOYED}
    dateFormat="relative"
    now={NOW}
    locale="en-US"
  >
    Hover the time for the absolute date.
  </TimelineItem>
</Timeline>

January 5, 2026

A date on its own fills the header.

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".

With the time

March 9, 2026 at 2:30 PM

dateFormat takes Intl.DateTimeFormat options.

Relative

3 days ago

Hover the time for the absolute date.

// GENERATED from packages/demos/timeline/dates.demo.tsx — edit the source, not this file.
import { Timeline, TimelineItem } from "@pindoba/react-timeline";

const START = new Date(2026, 0, 5);
const END = new Date(2026, 2, 9);
const DEPLOYED = new Date(2026, 2, 9, 14, 30);
const NOW = new Date(2026, 2, 12, 9, 0);
export default function DatesDemo() {
  return (
    <Timeline>
      <TimelineItem date={START} locale="en-US">
        A date on its own fills the header.
      </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>
      <TimelineItem
        title="With the time"
        date={DEPLOYED}
        locale="en-US"
        dateFormat={{
          year: "numeric",
          month: "long",
          day: "numeric",
          hour: "numeric",
          minute: "2-digit",
        }}
      >
        <code>dateFormat</code> takes <code>Intl.DateTimeFormat</code> options.
      </TimelineItem>
      <TimelineItem
        title="Relative"
        date={DEPLOYED}
        dateFormat="relative"
        now={NOW}
        locale="en-US"
      >
        Hover the time for the absolute date.
      </TimelineItem>
    </Timeline>
  );
}

January 5, 2026

A date on its own fills the header.

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".

With the time

March 9, 2026 at 2:30 PM

dateFormat takes Intl.DateTimeFormat options.

Relative

3 days ago

Hover the time for the absolute date.

<script lang="ts">
  // GENERATED from packages/demos/timeline/dates.demo.tsx — edit the source, not this file.
  import Timeline from "@pindoba/svelte-timeline";
  import { TimelineItem } from "@pindoba/svelte-timeline";

  const START = new Date(2026, 0, 5);
  const END = new Date(2026, 2, 9);
  const DEPLOYED = new Date(2026, 2, 9, 14, 30);
  const NOW = new Date(2026, 2, 12, 9, 0);
</script>

<Timeline>
  <TimelineItem date={START} locale="en-US">
    A date on its own fills the header.
  </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>
  <TimelineItem
    title="With the time"
    date={DEPLOYED}
    locale="en-US"
    dateFormat={{
      year: "numeric",
      month: "long",
      day: "numeric",
      hour: "numeric",
      minute: "2-digit",
    }}
  >
    <code> dateFormat </code> takes <code> Intl.DateTimeFormat </code> options.
  </TimelineItem>
  <TimelineItem
    title="Relative"
    date={DEPLOYED}
    dateFormat="relative"
    now={NOW}
    locale="en-US"
  >
    Hover the time for the absolute date.
  </TimelineItem>
</Timeline>

January 5, 2026

A date on its own fills the header.

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".

With the time

March 9, 2026 at 2:30 PM

dateFormat takes Intl.DateTimeFormat options.

Relative

3 days ago

Hover the time for the absolute date.

<script setup lang="ts">
// GENERATED from packages/demos/timeline/dates.demo.tsx — edit the source, not this file.
import { Timeline, TimelineItem } from "@pindoba/vue-timeline";

const START = new Date(2026, 0, 5);
const END = new Date(2026, 2, 9);
const DEPLOYED = new Date(2026, 2, 9, 14, 30);
const NOW = new Date(2026, 2, 12, 9, 0);
</script>

<template>
  <Timeline>
    <TimelineItem :date="START" locale="en-US"
      >A date on its own fills the header.</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>
    <TimelineItem
      title="With the time"
      :date="DEPLOYED"
      locale="en-US"
      :dateFormat="{
        year: 'numeric',
        month: 'long',
        day: 'numeric',
        hour: 'numeric',
        minute: '2-digit',
      }"
    >
      <code>dateFormat</code> takes <code>Intl.DateTimeFormat</code> options.
    </TimelineItem>
    <TimelineItem
      title="Relative"
      :date="DEPLOYED"
      dateFormat="relative"
      :now="NOW"
      locale="en-US"
    >
      Hover the time for the absolute date.
    </TimelineItem>
  </Timeline>
</template>

January 5, 2026

A date on its own fills the header.

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".

With the time

March 9, 2026 at 2:30 PM

dateFormat takes Intl.DateTimeFormat options.

Relative

3 days ago

Hover the time for the absolute date.

// GENERATED from packages/demos/timeline/dates.demo.tsx — edit the source, not this file.
import { Timeline, TimelineItem } from "@pindoba/solid-timeline";

const START = new Date(2026, 0, 5);
const END = new Date(2026, 2, 9);
const DEPLOYED = new Date(2026, 2, 9, 14, 30);
const NOW = new Date(2026, 2, 12, 9, 0);
export default function DatesDemo() {
  return (
    <Timeline>
      <TimelineItem date={START} locale="en-US">
        A date on its own fills the header.
      </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>
      <TimelineItem
        title="With the time"
        date={DEPLOYED}
        locale="en-US"
        dateFormat={{
          year: "numeric",
          month: "long",
          day: "numeric",
          hour: "numeric",
          minute: "2-digit",
        }}
      >
        <code>dateFormat</code> takes <code>Intl.DateTimeFormat</code> options.
      </TimelineItem>
      <TimelineItem
        title="Relative"
        date={DEPLOYED}
        dateFormat="relative"
        now={NOW}
        locale="en-US"
      >
        Hover the time for the absolute date.
      </TimelineItem>
    </Timeline>
  );
}

Step states

To track progress through known steps (an order going Received → In production → Ready → Picked up), give each entry a state. With no custom marker, the marker becomes a state stamp, and tone defaults to primary:

done: a filled stamp with a check. The line after it takes the item’s colour.
current: a filled stamp with a ring. The entry carries aria-current="step".
upcoming: a hollow, muted stamp. The heading and body use the muted text colour, a solved token that stays readable, never an opacity fade.

A line leading into an upcoming step is muted even when it starts at a done one. The last entry draws no line. That is plain CSS keyed on the item being the timeline’s last child, so render entries as direct children of Timeline, or of a TimelineCollapse region.

PreviewCode

Received

9:12 AM

Completed

Order #1042 — 2 flat whites, 1 croissant.

In production

9:40 AM

Completed

The kitchen started on it.

Ready

Current step

Waiting at the counter.

Picked up

Not started

Show the code 1042 at pickup.

---
// GENERATED from packages/demos/timeline/steps.demo.tsx — edit the source, not this file.
import { Timeline, TimelineItem } from "@pindoba/astro-timeline";

const RECEIVED = new Date(2026, 8, 28, 9, 12);
const IN_PRODUCTION = new Date(2026, 8, 28, 9, 40);
const TIME = {
  hour: "numeric",
  minute: "2-digit",
} as const;
---

<Timeline>
  <TimelineItem
    state="done"
    title="Received"
    date={RECEIVED}
    dateFormat={TIME}
    locale="en-US"
  >
    Order #1042 — 2 flat whites, 1 croissant.
  </TimelineItem>
  <TimelineItem
    state="done"
    title="In production"
    date={IN_PRODUCTION}
    dateFormat={TIME}
    locale="en-US"
  >
    The kitchen started on it.
  </TimelineItem>
  <TimelineItem state="current" title="Ready">
    Waiting at the counter.
  </TimelineItem>
  <TimelineItem state="upcoming" title="Picked up">
    Show the code 1042 at pickup.
  </TimelineItem>
</Timeline>

Received

9:12 AM

Completed

Order #1042 — 2 flat whites, 1 croissant.

In production

9:40 AM

Completed

The kitchen started on it.

Ready

Current step

Waiting at the counter.

Picked up

Not started

Show the code 1042 at pickup.

// GENERATED from packages/demos/timeline/steps.demo.tsx — edit the source, not this file.
import { Timeline, TimelineItem } from "@pindoba/react-timeline";

const RECEIVED = new Date(2026, 8, 28, 9, 12);
const IN_PRODUCTION = new Date(2026, 8, 28, 9, 40);
const TIME = {
  hour: "numeric",
  minute: "2-digit",
} as const;
export default function StepsDemo() {
  return (
    <Timeline>
      <TimelineItem
        state="done"
        title="Received"
        date={RECEIVED}
        dateFormat={TIME}
        locale="en-US"
      >
        Order #1042 — 2 flat whites, 1 croissant.
      </TimelineItem>
      <TimelineItem
        state="done"
        title="In production"
        date={IN_PRODUCTION}
        dateFormat={TIME}
        locale="en-US"
      >
        The kitchen started on it.
      </TimelineItem>
      <TimelineItem state="current" title="Ready">
        Waiting at the counter.
      </TimelineItem>
      <TimelineItem state="upcoming" title="Picked up">
        Show the code 1042 at pickup.
      </TimelineItem>
    </Timeline>
  );
}

Received

9:12 AM

Completed

Order #1042 — 2 flat whites, 1 croissant.

In production

9:40 AM

Completed

The kitchen started on it.

Ready

Current step

Waiting at the counter.

Picked up

Not started

Show the code 1042 at pickup.

<script lang="ts">
  // GENERATED from packages/demos/timeline/steps.demo.tsx — edit the source, not this file.
  import Timeline from "@pindoba/svelte-timeline";
  import { TimelineItem } from "@pindoba/svelte-timeline";

  const RECEIVED = new Date(2026, 8, 28, 9, 12);
  const IN_PRODUCTION = new Date(2026, 8, 28, 9, 40);
  const TIME = {
    hour: "numeric",
    minute: "2-digit",
  } as const;
</script>

<Timeline>
  <TimelineItem
    state="done"
    title="Received"
    date={RECEIVED}
    dateFormat={TIME}
    locale="en-US"
  >
    Order #1042 — 2 flat whites, 1 croissant.
  </TimelineItem>
  <TimelineItem
    state="done"
    title="In production"
    date={IN_PRODUCTION}
    dateFormat={TIME}
    locale="en-US"
  >
    The kitchen started on it.
  </TimelineItem>
  <TimelineItem state="current" title="Ready">
    Waiting at the counter.
  </TimelineItem>
  <TimelineItem state="upcoming" title="Picked up">
    Show the code 1042 at pickup.
  </TimelineItem>
</Timeline>

Received

9:12 AM

Completed

Order #1042 — 2 flat whites, 1 croissant.

In production

9:40 AM

Completed

The kitchen started on it.

Ready

Current step

Waiting at the counter.

Picked up

Not started

Show the code 1042 at pickup.

<script setup lang="ts">
// GENERATED from packages/demos/timeline/steps.demo.tsx — edit the source, not this file.
import { Timeline, TimelineItem } from "@pindoba/vue-timeline";

const RECEIVED = new Date(2026, 8, 28, 9, 12);
const IN_PRODUCTION = new Date(2026, 8, 28, 9, 40);
const TIME = {
  hour: "numeric",
  minute: "2-digit",
} as const;
</script>

<template>
  <Timeline>
    <TimelineItem
      state="done"
      title="Received"
      :date="RECEIVED"
      :dateFormat="TIME"
      locale="en-US"
    >
      Order #1042 — 2 flat whites, 1 croissant.
    </TimelineItem>
    <TimelineItem
      state="done"
      title="In production"
      :date="IN_PRODUCTION"
      :dateFormat="TIME"
      locale="en-US"
    >
      The kitchen started on it.
    </TimelineItem>
    <TimelineItem state="current" title="Ready"
      >Waiting at the counter.</TimelineItem
    >
    <TimelineItem state="upcoming" title="Picked up"
      >Show the code 1042 at pickup.</TimelineItem
    >
  </Timeline>
</template>

Received

9:12 AM

Completed

Order #1042 — 2 flat whites, 1 croissant.

In production

9:40 AM

Completed

The kitchen started on it.

Ready

Current step

Waiting at the counter.

Picked up

Not started

Show the code 1042 at pickup.

// GENERATED from packages/demos/timeline/steps.demo.tsx — edit the source, not this file.
import { Timeline, TimelineItem } from "@pindoba/solid-timeline";

const RECEIVED = new Date(2026, 8, 28, 9, 12);
const IN_PRODUCTION = new Date(2026, 8, 28, 9, 40);
const TIME = {
  hour: "numeric",
  minute: "2-digit",
} as const;
export default function StepsDemo() {
  return (
    <Timeline>
      <TimelineItem
        state="done"
        title="Received"
        date={RECEIVED}
        dateFormat={TIME}
        locale="en-US"
      >
        Order #1042 — 2 flat whites, 1 croissant.
      </TimelineItem>
      <TimelineItem
        state="done"
        title="In production"
        date={IN_PRODUCTION}
        dateFormat={TIME}
        locale="en-US"
      >
        The kitchen started on it.
      </TimelineItem>
      <TimelineItem state="current" title="Ready">
        Waiting at the counter.
      </TimelineItem>
      <TimelineItem state="upcoming" title="Picked up">
        Show the code 1042 at pickup.
      </TimelineItem>
    </Timeline>
  );
}

A cancelled order stops early. Its last step is the current one, with tone="danger" and its own marker.

PreviewCode

Received

Completed

Order #1043 — 1 espresso.

In production

Completed

The kitchen started on it.

Cancelled

Final status

Out of oat milk — the payment was refunded.

---
// GENERATED from packages/demos/timeline/steps-cancelled.demo.tsx — edit the source, not this file.
import Stamp from "@pindoba/astro-stamp";
import { Timeline, TimelineItem } from "@pindoba/astro-timeline";
import { X } from "@lucide/astro";
---

<Timeline>
  <TimelineItem state="done" title="Received">
    Order #1043 — 1 espresso.
  </TimelineItem>
  <TimelineItem state="done" title="In production">
    The kitchen started on it.
  </TimelineItem>
  <TimelineItem
    state="current"
    tone="danger"
    title="Cancelled"
    labels={{ current: "Final status" }}
  >
    <Stamp slot="marker" emphasis="primary" tone="danger" shape="circle">
      <X />
    </Stamp>
    Out of oat milk — the payment was refunded.
  </TimelineItem>
</Timeline>

Received

Completed

Order #1043 — 1 espresso.

In production

Completed

The kitchen started on it.

Cancelled

Final status

Out of oat milk — the payment was refunded.

// GENERATED from packages/demos/timeline/steps-cancelled.demo.tsx — edit the source, not this file.
import { Stamp } from "@pindoba/react-stamp";
import { Timeline, TimelineItem } from "@pindoba/react-timeline";
import { X } from "lucide-react";

export default function StepsCancelledDemo() {
  return (
    <Timeline>
      <TimelineItem state="done" title="Received">
        Order #1043 — 1 espresso.
      </TimelineItem>
      <TimelineItem state="done" title="In production">
        The kitchen started on it.
      </TimelineItem>
      <TimelineItem
        state="current"
        tone="danger"
        title="Cancelled"
        labels={{ current: "Final status" }}
        marker={
          <Stamp emphasis="primary" tone="danger" shape="circle">
            <X />
          </Stamp>
        }
      >
        Out of oat milk — the payment was refunded.
      </TimelineItem>
    </Timeline>
  );
}

Received

Completed

Order #1043 — 1 espresso.

In production

Completed

The kitchen started on it.

Cancelled

Final status

Out of oat milk — the payment was refunded.

<script lang="ts">
  // GENERATED from packages/demos/timeline/steps-cancelled.demo.tsx — edit the source, not this file.
  import Stamp from "@pindoba/svelte-stamp";
  import Timeline from "@pindoba/svelte-timeline";
  import { TimelineItem } from "@pindoba/svelte-timeline";
  import LucideX from "@lucide/svelte/icons/x";
</script>

<Timeline>
  <TimelineItem state="done" title="Received">
    Order #1043 — 1 espresso.
  </TimelineItem>
  <TimelineItem state="done" title="In production">
    The kitchen started on it.
  </TimelineItem>
  <TimelineItem
    state="current"
    tone="danger"
    title="Cancelled"
    labels={{ current: "Final status" }}
  >
    {#snippet marker()}
      <Stamp emphasis="primary" tone="danger" shape="circle">
        <LucideX />
      </Stamp>
    {/snippet}
    Out of oat milk — the payment was refunded.
  </TimelineItem>
</Timeline>

Received

Completed

Order #1043 — 1 espresso.

In production

Completed

The kitchen started on it.

Cancelled

Final status

Out of oat milk — the payment was refunded.

<script setup lang="ts">
// GENERATED from packages/demos/timeline/steps-cancelled.demo.tsx — edit the source, not this file.
import { Stamp } from "@pindoba/vue-stamp";
import { Timeline, TimelineItem } from "@pindoba/vue-timeline";
</script>

<template>
  <Timeline>
    <TimelineItem state="done" title="Received"
      >Order #1043 — 1 espresso.</TimelineItem
    >
    <TimelineItem state="done" title="In production"
      >The kitchen started on it.</TimelineItem
    >
    <TimelineItem
      state="current"
      tone="danger"
      title="Cancelled"
      :labels="{ current: 'Final status' }"
    >
      <template #marker>
        <Stamp emphasis="primary" tone="danger" shape="circle">
          <svg
            xmlns="http://www.w3.org/2000/svg"
            width="24"
            height="24"
            viewBox="0 0 24 24"
            fill="none"
            stroke="currentColor"
            stroke-width="2"
            stroke-linecap="round"
            stroke-linejoin="round"
            class="lucide lucide-x"
            aria-hidden="true"
          >
            <path d="M18 6 6 18" />
            <path d="m6 6 12 12" />
          </svg>
        </Stamp>
      </template>
      Out of oat milk — the payment was refunded.
    </TimelineItem>
  </Timeline>
</template>

Received

Completed

Order #1043 — 1 espresso.

In production

Completed

The kitchen started on it.

Cancelled

Final status

Out of oat milk — the payment was refunded.

// GENERATED from packages/demos/timeline/steps-cancelled.demo.tsx — edit the source, not this file.
import { Stamp } from "@pindoba/solid-stamp";
import { Timeline, TimelineItem } from "@pindoba/solid-timeline";

export default function StepsCancelledDemo() {
  return (
    <Timeline>
      <TimelineItem state="done" title="Received">
        Order #1043 — 1 espresso.
      </TimelineItem>
      <TimelineItem state="done" title="In production">
        The kitchen started on it.
      </TimelineItem>
      <TimelineItem
        state="current"
        tone="danger"
        title="Cancelled"
        labels={{ current: "Final status" }}
        marker={
          <Stamp emphasis="primary" tone="danger" shape="circle">
            <svg
              xmlns="http://www.w3.org/2000/svg"
              width="24"
              height="24"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              stroke-width="2"
              stroke-linecap="round"
              stroke-linejoin="round"
              class="lucide lucide-x"
              aria-hidden="true"
            >
              <path d="M18 6 6 18" />
              <path d="m6 6 12 12" />
            </svg>
          </Stamp>
        }
      >
        Out of oat milk — the payment was refunded.
      </TimelineItem>
    </Timeline>
  );
}

Announcing the state

A screen reader can’t see the marker, so every entry with a state also renders a visually hidden word after its heading: “Completed”, “Current step” or “Not started”. Localize it with labels. Keys you leave out keep the English default:

<TimelineItem state="done" title="Recebido" labels={{ done: "Concluído" }} />

If the visible content already names the state (a “Cancelled” title, a status badge), turn the word off. labels={false} removes it for every state, and an empty string removes it for one (labels={{ current: "" }}).

Framework support

TimelineSeparator and TimelineCollapse ship for Svelte and Astro. React, Vue and Solid render Timeline and TimelineItem with the full anatomy (marker, heading, meta, body and actions); the separator and collapse ports are tracked in the core roadmap.

#Activity log

#Header tiers

#Comments and threads

#Collapsing entries

#Markers

#Sizes and lines

#Dates

#Step states

#Announcing the state

#Framework support

Activity log

Header tiers

Comments and threads

Collapsing entries

Markers

Sizes and lines

Dates

Step states

Announcing the state

Framework support