@edux-design/event-timeline

Event-based timeline for timestamped history, status changes, and audit-style activity streams.

The API is modeled after Zendesk Garden's Timeline compound component:

• Timeline
• Timeline.Item
• Timeline.OppositeContent
• Timeline.Content

This package keeps that declarative shape but uses Edux theme tokens and utility classes.

Install

npm install @edux-design/event-timeline

Usage

import { EventTimeline } from "@edux-design/event-timeline";

export function Example() {
  return (
    <EventTimeline>
      <EventTimeline.Item markerTone="info" markerVariant="outline">
        <EventTimeline.Content>
          <EventTimeline.Title>Manuscript status changed</EventTimeline.Title>
          <EventTimeline.Meta>
            <time dateTime="2026-06-07T10:42:00">Today 10:42 AM</time>
          </EventTimeline.Meta>
          <EventTimeline.Description>
            The manuscript moved from internal review to editorial QA.
          </EventTimeline.Description>
        </EventTimeline.Content>
      </EventTimeline.Item>

      <EventTimeline.Item
        markerTone="success"
        markerVariant="solid"
        markerClassName="shadow-sm"
        icon={<StatusDot />}
      >
        <EventTimeline.Content>
          <EventTimeline.Title>Approval note added</EventTimeline.Title>
          <EventTimeline.Meta>
            <time dateTime="2026-06-06T15:18:00">June 6, 3:18 PM</time>
          </EventTimeline.Meta>
          <EventTimeline.Description>
            Sign-off was recorded with linked review notes.
          </EventTimeline.Description>
        </EventTimeline.Content>
      </EventTimeline.Item>
    </EventTimeline>
  );
}

API

EventTimeline

Extends OlHTMLAttributes<HTMLOListElement>.

| Prop | Type | Default | Description | | --- | --- | --- | --- | | isAlternate | boolean | false | Alternates event content between the left and right columns on desktop layouts. |

EventTimeline.Item

Extends LiHTMLAttributes<HTMLLIElement>.

| Prop | Type | Default | Description | | --- | --- | --- | --- | | icon | ReactNode | | Replaces the default dot with custom media such as an icon, avatar, or image. | | markerTone | "default" \| "info" \| "success" \| "warning" \| "danger" | "default" | Applies token-based colors to the marker and connecting line. | | markerVariant | "subtle" \| "outline" \| "solid" | "subtle" | Uses predefined token-driven marker treatments instead of ad hoc styling. | | markerClassName | string | | Escape hatch for consumer-specific marker overrides after token-driven variants are applied. | | markerInnerClassName | string | | Escape hatch for styling the inner dot or icon wrapper. | | surfaceColor | string | | Optional last-resort background override for the marker. Prefer markerTone + markerVariant first. |

EventTimeline.OppositeContent

Extends HTMLAttributes<HTMLDivElement>.

Use this slot for timestamps, date labels, or supporting metadata that should sit opposite the main event card.

EventTimeline.Content

Extends HTMLAttributes<HTMLDivElement>.

Primary event surface. By default it renders as plain flow content so the marker rail stays visually dominant.

EventTimeline.Title

Extends HTMLAttributes<HTMLDivElement>.

Convenience text wrapper for event titles.

EventTimeline.Meta

Extends HTMLAttributes<HTMLDivElement>.

Convenience row for secondary metadata such as actor, category, or channel.

EventTimeline.Description

Extends HTMLAttributes<HTMLDivElement>.

Convenience wrapper for longer event copy.

Notes

• Mobile layouts collapse into a single event column while preserving the opposite timestamp content above each event card.
• The default layout is a Zendesk-style vertical activity list: marker rail on the left, event content on the right.
• For event timestamps, prefer semantic <time dateTime="...">...</time> content inside Timeline.Meta or Timeline.OppositeContent.
• For marker styling, prefer markerTone + markerVariant and use markerClassName only as a consumer override escape hatch.
• Timeline is also exported as an alias if you want the same naming shape as Zendesk Garden inside this package.