Timeline
⋯
Timeline implements the activity-note anatomy from Figma with semantic ordered-list markup. It composes existing Avatar and Badge components rather than owning product-specific activity data.
import { Avatar } from "@nesra/ui/avatar";import { Timeline } from "@nesra/ui/timeline";
export function ActivityHistory() { return ( <Timeline aria-labelledby="activity-title"> <Timeline.Heading id="activity-title">Activity</Timeline.Heading> <Timeline.List aria-label="Activity history"> <Timeline.Item> <Timeline.Time dateTime="2026-09-20T15:10:00Z">Sep 20, 2026</Timeline.Time> <Timeline.Marker> <Avatar initials="I" name="Irni Susanti" /> </Timeline.Marker> <Timeline.Content>Updated payment terms</Timeline.Content> </Timeline.Item> </Timeline.List> </Timeline> );}The exports are also available from @nesra/ui.
Composition
Section titled “Composition”Timeline├── Timeline.Heading└── Timeline.List └── Timeline.Item × n ├── Timeline.Time ├── Timeline.Marker │ └── Avatar or another 24px visual └── Timeline.Content ├── Timeline.ItemHeader │ ├── Timeline.Actor │ │ ├── Timeline.ActorName │ │ └── Timeline.ActorMeta │ └── Timeline.Separator and consumer metadata └── Timeline.Note ├── Timeline.NoteLabel └── Timeline.NoteContentExamples
Section titled “Examples”Activity log
Section titled “Activity log”import { Avatar } from "@nesra/ui/avatar";import { Badge } from "@nesra/ui/badge";import { Timeline } from "@nesra/ui/timeline";
export function TimelineActivityExample() { return ( <Timeline className="max-w-3xl" aria-labelledby="activity-title"> <Timeline.Heading id="activity-title">Activity notes</Timeline.Heading> <Timeline.List aria-label="Activity history"> <Timeline.Item> <Timeline.Time dateTime="2026-09-20T15:10:00+07:00"> Sep 20, 2026, <br /> 15:10 </Timeline.Time> <Timeline.Marker> <Avatar initials="I" name="Irni Susanti" /> </Timeline.Marker> <Timeline.Content> <Timeline.ItemHeader> <Timeline.Actor> <Timeline.ActorName>Irni Susanti</Timeline.ActorName> <Timeline.ActorMeta>AP Team</Timeline.ActorMeta> </Timeline.Actor> <Timeline.Separator /> <Badge color="warning" size="sm"> Edit </Badge> <Timeline.Separator /> <span>Updated payment terms</span> <Timeline.Separator /> <span> Default term:{" "} <strong className="font-medium text-nesra-text-body">14 days → 30 days</strong> </span> </Timeline.ItemHeader> <Timeline.Note> <Timeline.NoteLabel>Note</Timeline.NoteLabel> <Timeline.NoteContent>Renegotiated contract terms</Timeline.NoteContent> </Timeline.Note> </Timeline.Content> </Timeline.Item> <Timeline.Item> <Timeline.Time dateTime="2026-08-05T09:00:00+07:00"> Aug 5, 2026, <br /> 09:00 </Timeline.Time> <Timeline.Marker> <Avatar initials="M" name="Michael Owen" /> </Timeline.Marker> <Timeline.Content> <Timeline.ItemHeader> <Timeline.Actor> <Timeline.ActorName>Michael Owen</Timeline.ActorName> <Timeline.ActorMeta>Lead</Timeline.ActorMeta> </Timeline.Actor> <Timeline.Separator /> <Badge color="info" size="sm"> Create </Badge> <Timeline.Separator /> <span>Added a new vendor</span> </Timeline.ItemHeader> <Timeline.Note> <Timeline.NoteLabel>Note</Timeline.NoteLabel> <Timeline.NoteContent muted>No note yet</Timeline.NoteContent> </Timeline.Note> </Timeline.Content> </Timeline.Item> </Timeline.List> </Timeline> );}Approval history
Section titled “Approval history”Compose Avatar, Badge, actor metadata, and an optional decision note for multi-step approvals.
import { Avatar } from "@nesra/ui/avatar";import { Badge } from "@nesra/ui/badge";import { Timeline } from "@nesra/ui/timeline";
export function TimelineApprovalExample() { return ( <Timeline className="max-w-3xl" aria-labelledby="approval-history-title"> <Timeline.Heading id="approval-history-title">Approval history</Timeline.Heading> <Timeline.List aria-label="Invoice approval history"> <Timeline.Item> <Timeline.Time dateTime="2026-09-24T10:30:00+07:00"> Sep 24, 2026, <br /> 10:30 </Timeline.Time> <Timeline.Marker> <Avatar initials="D" name="Dewi Wulandari" /> </Timeline.Marker> <Timeline.Content> <Timeline.ItemHeader> <Timeline.Actor> <Timeline.ActorName>Dewi Wulandari</Timeline.ActorName> <Timeline.ActorMeta>Finance Director</Timeline.ActorMeta> </Timeline.Actor> <Timeline.Separator /> <Badge color="success" size="sm"> Approved </Badge> <Timeline.Separator /> <span>Approved invoice INV-2026-0912</span> </Timeline.ItemHeader> <Timeline.Note> <Timeline.NoteLabel>Decision note</Timeline.NoteLabel> <Timeline.NoteContent>Budget and supporting documents verified.</Timeline.NoteContent> </Timeline.Note> </Timeline.Content> </Timeline.Item> <Timeline.Item> <Timeline.Time dateTime="2026-09-24T09:15:00+07:00"> Sep 24, 2026, <br /> 09:15 </Timeline.Time> <Timeline.Marker> <Avatar initials="R" name="Rizky Ananda" /> </Timeline.Marker> <Timeline.Content> <Timeline.ItemHeader> <Timeline.Actor> <Timeline.ActorName>Rizky Ananda</Timeline.ActorName> <Timeline.ActorMeta>AP Manager</Timeline.ActorMeta> </Timeline.Actor> <Timeline.Separator /> <Badge color="warning" size="sm"> Review </Badge> <Timeline.Separator /> <span>Requested director approval</span> </Timeline.ItemHeader> </Timeline.Content> </Timeline.Item> </Timeline.List> </Timeline> );}Custom markers
Section titled “Custom markers”The marker slot accepts any 24px visual. Hide decorative icons when the adjacent content already communicates the event.
import { Check, FilePenLine, Upload } from "lucide-react";import type { ReactNode } from "react";import { Timeline } from "@nesra/ui/timeline";
function IconMarker({ children }: { children: ReactNode }) { return ( <span className="flex size-6 items-center justify-center rounded-full border border-nesra-stroke-divider bg-nesra-surface-card-bg-brand-primary-50 text-nesra-text-brand-primary [&>svg]:size-3"> {children} </span> );}
const events = [ { dateTime: "2026-09-24T11:05:00+07:00", time: "11:05", title: "Document signed", description: "All signatories completed the document", icon: <Check key="signed" />, }, { dateTime: "2026-09-24T10:42:00+07:00", time: "10:42", title: "Signature requested", description: "Sent to two reviewers", icon: <FilePenLine key="requested" />, }, { dateTime: "2026-09-24T10:30:00+07:00", time: "10:30", title: "Document uploaded", description: "vendor-agreement.pdf", icon: <Upload key="uploaded" />, },];
export function TimelineCustomMarkersExample() { return ( <Timeline className="max-w-3xl" aria-labelledby="document-history-title"> <Timeline.Heading id="document-history-title">Document history</Timeline.Heading> <Timeline.List aria-label="Document history"> {events.map((event) => ( <Timeline.Item key={event.dateTime}> <Timeline.Time dateTime={event.dateTime}>{event.time}</Timeline.Time> <Timeline.Marker aria-hidden="true"> <IconMarker>{event.icon}</IconMarker> </Timeline.Marker> <Timeline.Content> <Timeline.ItemHeader> <Timeline.ActorName>{event.title}</Timeline.ActorName> <Timeline.Separator /> <span>{event.description}</span> </Timeline.ItemHeader> </Timeline.Content> </Timeline.Item> ))} </Timeline.List> </Timeline> );}Minimal events
Section titled “Minimal events”Omit actor metadata, badges, and note surfaces when the event label is sufficient.
import { Timeline } from "@nesra/ui/timeline";
const events = [ ["2026-09-24T11:30:00+07:00", "11:30", "Payment completed"], ["2026-09-24T10:10:00+07:00", "10:10", "Payment processing started"], ["2026-09-24T09:45:00+07:00", "09:45", "Payment submitted"],] as const;
export function TimelineMinimalExample() { return ( <Timeline className="max-w-2xl" aria-labelledby="recent-events-title"> <Timeline.Heading id="recent-events-title">Recent events</Timeline.Heading> <Timeline.List aria-label="Recent payment events"> {events.map(([dateTime, time, label]) => ( <Timeline.Item key={dateTime}> <Timeline.Time dateTime={dateTime}>{time}</Timeline.Time> <Timeline.Marker aria-hidden="true"> <span className="flex size-6 items-start justify-center pt-1"> <span className="size-2 rounded-full bg-nesra-icon-brand-primary" /> </span> </Timeline.Marker> <Timeline.Content> <Timeline.ItemHeader> <Timeline.ActorName>{label}</Timeline.ActorName> </Timeline.ItemHeader> </Timeline.Content> </Timeline.Item> ))} </Timeline.List> </Timeline> );}Long content
Section titled “Long content”Headers and note content wrap without changing the marker or connector alignment.
import { Clock3 } from "lucide-react";import { Timeline } from "@nesra/ui/timeline";
export function TimelineLongContentExample() { return ( <Timeline className="max-w-2xl" aria-labelledby="case-history-title"> <Timeline.Heading id="case-history-title">Case history</Timeline.Heading> <Timeline.List aria-label="Case history"> <Timeline.Item> <Timeline.Time dateTime="2026-09-24T08:45:00+07:00"> Sep 24, 2026, <br /> 08:45 </Timeline.Time> <Timeline.Marker aria-hidden="true"> <span className="flex size-6 items-center justify-center rounded-full border border-nesra-stroke-divider bg-nesra-surface-card-bg-brand-primary-50 text-nesra-text-brand-primary"> <Clock3 className="size-3" /> </span> </Timeline.Marker> <Timeline.Content> <Timeline.ItemHeader> <Timeline.ActorName>Automatic review scheduled</Timeline.ActorName> <Timeline.Separator /> <span> The case will be reviewed again after all requested supporting documents arrive. </span> </Timeline.ItemHeader> <Timeline.Note> <Timeline.NoteLabel>Additional context</Timeline.NoteLabel> <Timeline.NoteContent> The vendor was notified by email and can upload the missing tax certificate and bank ownership letter through the supplier portal. </Timeline.NoteContent> </Timeline.Note> </Timeline.Content> </Timeline.Item> </Timeline.List> </Timeline> );}At widths below the sm breakpoint, the timestamp moves above the entry content while the marker stays in the first column. The desktop layout uses the Figma 100px timestamp column.
Light and Dark
Section titled “Light and Dark”Timeline uses semantic roles only and follows the page theme through .dark or
data-theme="dark". Times, actor context, note labels, and muted note content use
--nesra-text-support. Names and note content use --nesra-text-body. The note surface uses
--nesra-surface-card-bg-neutral with a --nesra-stroke-border border, and the connector uses
--nesra-stroke-divider. Figma has no Timeline component yet, so these roles follow the color
contract rather than a Figma component.
Accessibility
Section titled “Accessibility”Timeline.Listrenders an ordered list andTimeline.Itemrenders each list item.- Supply a machine-readable
dateTimeon everyTimeline.Time. - Name the timeline through visible heading association or an
aria-labelon the list. Timeline.Markerdoes not hide its child. Avatar names and other meaningful marker content remain exposed.Timeline.Separatoris decorative and hidden from assistive technology.
API reference
Section titled “API reference”Timeline and Timeline.Heading
Section titled “Timeline and Timeline.Heading”Timeline forwards native div props. Timeline.Heading accepts as with "h2" through "h6" and defaults to "h2". Choose the heading level from the surrounding page hierarchy.
Timeline.List and Timeline.Item
Section titled “Timeline.List and Timeline.Item”Timeline.List forwards native ol props. Timeline.Item forwards native li props and owns the responsive time, marker, and content grid.
Timeline.Time
Section titled “Timeline.Time”Timeline.Time forwards native time props. Set dateTime to an ISO or otherwise machine-readable timestamp. Children supply the visible localized date and time.
Timeline.Marker and Timeline.Content
Section titled “Timeline.Marker and Timeline.Content”Timeline.Marker and Timeline.Content forward native div props. The marker draws a connector except on the last item and expects a 24px visual. Content groups the item header and optional body.
Timeline.ItemHeader and actor parts
Section titled “Timeline.ItemHeader and actor parts”Timeline.ItemHeader forwards native div props and wraps metadata. Timeline.Actor, Timeline.ActorName, and Timeline.ActorMeta forward native span props. Timeline.Separator forwards native span props except children and is always decorative.
Timeline.Note parts
Section titled “Timeline.Note parts”Timeline.Note forwards native div props. Timeline.NoteLabel and Timeline.NoteContent forward native p props. Timeline.NoteContent accepts muted, which defaults to false and applies the support text role to absent or placeholder copy.
Visual values come from the semantic color roles, typography, layout, and shape tokens.