Timeline

Anatomy

Nine parts, most of them plain layout. The three that do work are Timeline, which holds the orientation and the activeIndex; TimelineItem, which registers its position and derives its state from it; and TimelineConnector, which asks the next item for its state to decide its colour — and whether it is drawn at all.

import {
  Timeline, TimelineItem, TimelineDot, TimelineConnector, TimelineContent,
  TimelineHeader, TimelineTitle, TimelineTime, TimelineDescription,
} from '@comitor/ui'

<Timeline activeIndex={2}>             {/* role="list" — vertical unless you say otherwise */}
  <TimelineItem>                       {/* role="listitem" — completed, active or pending */}
    <TimelineDot />                    {/* an empty ring, or whatever you put in it */}
    <TimelineConnector />              {/* the line to the next item — none after the last */}
    <TimelineContent>
      <TimelineHeader>
        <TimelineTitle>Shipped</TimelineTitle>
        <TimelineTime dateTime="2026-08-28">Aug 28</TimelineTime>
      </TimelineHeader>
      <TimelineDescription>Handed to the carrier in Ho Chi Minh City.</TimelineDescription>
    </TimelineContent>
  </TimelineItem>
</Timeline>

Activity on a contact

A log, newest first. There is no activeIndex — in a record of what happened, nothing is current — so every ring keeps the neutral pending style and every line the decorative border colour. The dots are grown to 1.75rem through --timeline-dot-size to hold an icon; the connector reads the same variable, so it stays centred under them. The times are RelativeTime, merged into TimelineTime with asChild.

Where it stands: activeIndex

activeIndex is the zero-based position of the current item, counted over the rendered TimelineItems in document order. Everything else follows from it.

• Items before it are completed, the one at it is active — with aria-current="step" — and items after it are pending. The state is written to data-status on the item, its dot and its content.
• A connector is drawn in primary-ink when the item after it has been reached: the line leading into a completed or active step. The last item has none.
• Left out, every item is pending. activeIndex={items.length} marks every item completed and none current — the order below, once delivered.
• By default a completed dot and the active dot are the same ring. This demo tells them apart — a filled check, a centre dot — and works that out from its own index: the parts give their state to CSS, through data-status, but not to your code.

Alternate layout

variant="alternate" hangs every second item on the other side of a centre line, with the dots and the line on it — a career read at a glance. Each item takes half the width, so give the timeline room. Here the current role is the active item and the defaults are left alone: completed and active rings look the same, and every line leading into a reached role is drawn.

What the port guarantees

• The server render has the states. Upstream learned each item’s index in a layout effect, so on the server and in the first client render every index was −1 — and, compared with activeIndex, −1 painted every dot completed until hydration. The root now reads its items from its children as it renders, until they have registered, so the server HTML already has each state, aria-current, the connectors and the alternate sides. Where it cannot read them (Known limitations), an unknown index means pending — neutral, and right for most items — never completed.
• No aria-orientation on the list. ARIA 1.2 does not allow it on role="list", and axe reported it (aria-allowed-attr). The orientation stays in data-orientation.
• Colour by role. Reached dots and lines use primary-ink, the token for brand colour standing on the page, instead of the fill token primary. Pending dots use muted-foreground — 5.23:1 light, 5.70:1 dark, the same as StatusPill’s neutral outline — instead of the decorative border at 1.16:1. Lines not yet reached stay decorative.

Language

Timeline has no strings of its own and no namespace in ComitorLocaleProvider. TimelineTime renders a <time> and prints what you give it. So a time follows the language only if something that follows the language produced it: put RelativeTime inside it, which takes its date-fns locale from the provider, or format with Intl and useComitorLocale().locale (see setting the language). Switch the demo: only the times change. The titles and descriptions are yours to translate, the way the rest of your app does it.

Pass timeZone to every Intl formatter whose output is server-rendered — otherwise the server’s time zone and the reader’s can put the same event on different days, and React reports a hydration mismatch. RelativeTime is safe with a fixed now; its tooltip still uses the local zone, which it tolerates with suppressHydrationWarning. Formatting on the server works just as well:

// app/contacts/[id]/page.tsx — a Server Component. No part of Timeline needs a
// function prop, so the whole thing can be rendered here. The one cost: written in
// a Server Component, the items stay out of the root's sight until hydration, so
// the connecting lines only appear then (see Known limitations).
import { Timeline, TimelineItem, TimelineDot, TimelineConnector, TimelineContent,
  TimelineTitle, TimelineTime } from '@comitor/ui'

export default async function ContactPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  const activity = await getActivity(id)

  return (
    <Timeline>
      {activity.map((event) => (
        <TimelineItem key={event.id}>
          <TimelineDot />
          <TimelineConnector />
          <TimelineContent>
            <TimelineTitle>{event.title}</TimelineTitle>
            {/* Formatted here, on the server — TimelineTime prints it as given. */}
            <TimelineTime dateTime={event.at}>{formatDay(event.at)}</TimelineTime>
          </TimelineContent>
        </TimelineItem>
      ))}
    </Timeline>
  )
}

Props

Timeline

TimelineItem, TimelineDot, TimelineConnector

The text parts

Each renders one element with the classes below, takes asChild, and forwards its props.

Known limitations

• Items the root cannot see wait for hydration. The root reads its items from its children as it renders: each TimelineItem written directly in the Timeline, through .map, fragments, conditions and plain HTML elements. Anything else inside the timeline — a component of your own, a Suspense, a context provider — hides the items, and so does writing the tree straight in a Server Component. Then until the page hydrates every item is pending, none carries aria-current, no connector is drawn, and in the alternate layout every item sits on the first side — no mismatch warning, but a Next app shows that first frame. Write the items out in a client component; what goes inside a TimelineItem can still be your own. A client-only wrapper added before 3.1.0 to hide that frame can go.
• Completed and active look alike. Both get the same ring, and the line is the only difference. Style by data-status, or from your own index, and say the state in words (next section).
• The index is the document order. Items register themselves, so a conditionally rendered item — or a wrapper that reorders them visually — shifts activeIndex for every item after it.
• TimelineTime does not format. Upstream’s part never did; it is a styled <time>. See Language.

Accessibility

• The root is role="list" and each item role="listitem", so a screen reader announces “list, 5 items” and lets the reader step through them. Connectors are aria-hidden; dots are plain elements with no role.
• The active item carries aria-current="step". Completed and pending are not announced at all — they exist as colour and data-status only. Put the state in words: visible text, or an sr-only prefix as in the order demo.
• Do not lean on the ring colour either. primary-ink follows the palette. The default palette maps it to the brand gold itself: 12.67:1 on the dark background, but 1.86:1 on white — below the 3:1 a meaningful graphic needs. The high-contrast palette darkens it to 6.51:1 in light. Icons, fills and words carry the state in every palette.
• Icons inside a dot are decoration next to a title that says the same thing: mark them aria-hidden.
• TimelineTime is a real <time>. Give it a machine-readable dateTime; RelativeTime sets one for you, and a title with the absolute date.
• TimelineTitle is not a heading. On a long record page where people jump between events, render it as one with asChild.

Related