Skip to Content

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.

390 × 844

horizontal - Browse milestones along a horizontal rail.

390 × 844

alternating - Alternate event cards across the timeline.

390 × 844

centered - Place the timeline node between alternating events.

390 × 844

cards - Give each event a distinct content surface.

390 × 844

milestones - Emphasize important dates and turning points.

390 × 844

history - Give historical dates and details a calmer hierarchy.

390 × 844

editorial - Pair timeline events with editorial imagery.

390 × 844

compact - Fit a concise chronology into a smaller area.

390 × 844

numbered - Number each step in the sequence.

390 × 844

connected - Make the relationship between events explicit.

390 × 844

split - Separate event dates from their descriptions.

390 × 844

API

PropTypeDescription
variantTimelineSectionVariantvertical (default), horizontal, alternating, centered, cards, milestones, history, editorial, compact, numbered, connected, or split.
itemsreadonly TimelineEvent[]Events with stable, unique IDs and required titles.
TimelineEvent.datestringOptional valid date, formatted in UTC and exposed with <time>.
TimelineEvent.descriptionReactNodeOptional rich description.
TimelineEvent.imageEditorialImageOptional image with alt text, dimensions, loading preference, and caption.
TimelineEvent.iconReactNodeOptional decorative node icon; hidden from assistive technology.
TimelineEvent.actionReactNodeOptional consumer-provided link or action.
Shared section propsMarketingSectionBasePropsHeader, 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.

PropRequiredDefault
variantNo"vertical"
itemsYes—

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.