TimelineSection
Show ordered milestones with semantic event lists, dates, descriptions, imagery, icons, and optional actions.
TimelineSection presents ordered events as a vertical chronology, horizontal rail, milestone sequence, or editorial history. The caller controls event order and supplies all event content.
Beta API maturity: Beta.
Installation
import {
TimelineSection,
type TimelineEvent,
type TimelineSectionVariant,
} from "@puzzle-ui/pieces";Variant previews
Every variant is shown in its own preview with fictional Morrow studio milestones and editorial imagery.
vertical - Follow events in a clear top-to-bottom sequence.
horizontal - Browse milestones along a horizontal rail.
alternating - Alternate event cards across the timeline.
centered - Place the timeline node between alternating events.
cards - Give each event a distinct content surface.
milestones - Emphasize important dates and turning points.
history - Give historical dates and details a calmer hierarchy.
editorial - Pair timeline events with editorial imagery.
compact - Fit a concise chronology into a smaller area.
numbered - Number each step in the sequence.
connected - Make the relationship between events explicit.
split - Separate event dates from their descriptions.
API
| Prop | Type | Description |
|---|---|---|
variant | TimelineSectionVariant | vertical (default), horizontal, alternating, centered, cards, milestones, history, editorial, compact, numbered, connected, or split. |
items | readonly TimelineEvent[] | Events with stable, unique IDs and required titles. |
TimelineEvent.date | string | Optional valid date, formatted in UTC and exposed with <time>. |
TimelineEvent.description | ReactNode | Optional rich description. |
TimelineEvent.image | EditorialImage | Optional image with alt text, dimensions, loading preference, and caption. |
TimelineEvent.icon | ReactNode | Optional decorative node icon; hidden from assistive technology. |
TimelineEvent.action | ReactNode | Optional consumer-provided link or action. |
| Shared section props | MarketingSectionBaseProps | Header, root element, section attributes, actions, and children. |
Required and default values
Requiredness follows the exported TypeScript type. A dash means no component-level default is applied; variant-specific requirements are described in the API table above.
| Prop | Required | Default |
|---|---|---|
variant | No | "vertical" |
items | Yes | — |
Usage
const events: TimelineEvent[] = [
{
id: "studio-opened",
title: "Doors open at the studio",
date: "2024-04-06",
description: "Neighbors join us for workshops and a shared lunch.",
image: {
src: "/journal/open-studio.jpg",
alt: "Neighbors gathered around the studio table",
width: 1200,
height: 800,
caption: "Our first open studio afternoon.",
},
action: <a href="/journal/open-studio">Read the story</a>,
},
];
<TimelineSection
variant="connected"
title="A few moments that shaped our studio"
items={events}
/>;Dates are display metadata and do not reorder the array. Use the numbered variant to display sequence numbers; other variants show a node only when an icon is supplied. Image content is optional, and missing image sources use a labeled placeholder.
Accessibility and responsive behavior
Events render as an ordered list (<ol>) with each event in an <article>. Dates use <time>, icons are decorative, and caller-supplied actions retain their native semantics. The horizontal variant is a scrollable list; vertical connectors and alternating layouts adapt to the available viewport. The component does not access browser APIs and can render on the server.
Customization
Use the component's className and documented slots to adapt the composition. Prefer a caller-provided ReactNode for media, actions, or controls rather than adding domain behavior to the section.
import type { ComponentProps } from "react";
import { TimelineSection } from "@puzzle-ui/pieces";
type TimelineSectionProps = ComponentProps<typeof TimelineSection>;
export function CustomizedSection(props: TimelineSectionProps) {
return <TimelineSection {...props} className={[props.className, "brand-section"].filter(Boolean).join(" ")} />;
}Theme support
The section consumes semantic variables from @puzzle-ui/theme and inherits active or scoped themes. Wrap the application with Theme, and use semantic roles such as text, surface, border, and primary for local overrides. Avoid hard-coded colors, spacing, radii, and shadows.
.brand-section {
color: var(--puzzle-color-text);
background: var(--puzzle-color-surface);
border-color: var(--puzzle-color-border);
}Composition
Compose this section with the UI primitives named in its API and use the documented slots for consumer-owned controls or media. Keep data fetching, routing, validation, permissions, and persistence in the application. The children slot is intended for additional content that belongs with this section, not as a substitute for its typed data model.
TypeScript example
The package exports this component from its root. Derive a wrapper's exact prop type from the public component rather than widening it:
import type { ComponentProps } from "react";
import { TimelineSection } from "@puzzle-ui/pieces";
type TimelineSectionProps = ComponentProps<typeof TimelineSection>;
export function SectionWrapper(props: TimelineSectionProps) {
return <TimelineSection {...props} />;
}Framework compatibility
The section is router-independent. Static compositions can be server-rendered; place callback-driven interactions in the framework's client boundary. See Next.js and TanStack Start integration for runnable framework examples and SSR guidance.