Skip to Content

RoadmapSection

Present SaaS roadmap milestones by date, status, release, or group with optional accessible progress indicators.

RoadmapSection displays milestones in timeline, grouped, column, list, and kanban compositions. Status, date, progress, group, and release values are always provided by the caller.

Beta API maturity: Beta.

Installation

import {
  RoadmapSection,
  type RoadmapItem,
} from "@puzzle-ui/pieces";

Variant previews

Each of the twelve roadmap variants is previewed separately using illustrative release and milestone data.

timeline - Connect milestones along a vertical timeline.

390 × 844

quarters - Arrange milestones into quarter-like groups.

390 × 844

columns - Lay out custom groups as scrolling columns.

390 × 844

cards - Give each roadmap item a distinct card.

390 × 844

list - Keep dates and status in a compact list.

390 × 844

progress - Show only the progress values supplied for items.

390 × 844

horizontal - Scroll milestones along a horizontal timeline.

390 × 844

vertical - Use a simple vertical sequence without card chrome.

390 × 844

grouped - Separate items with headings for their groups.

390 × 844

kanban - Group items into columns by status.

390 × 844

milestones - Number ordered milestones along a connector.

390 × 844

release - Group milestones by their supplied release label.

390 × 844

API

PropTypeDescription
variantRoadmapVariantSelects one of twelve compositions; defaults to timeline.
itemsreadonly RoadmapItem[]Milestones with stable id, title, and required status.
RoadmapItem.status"planned" | "in-progress" | "completed" | "delayed" | "on-hold"Status rendered as visible text with a badge treatment.
RoadmapItem.statusLabelReactNodeOptional consumer-provided status label.
RoadmapItem.dateReactNodeOptional date or date label.
RoadmapItem.groupstringOptional group used by grouped, quarter, and column variants.
RoadmapItem.releasestringOptional release label used by the release variant.
RoadmapItem.descriptionReactNodeOptional milestone description.
RoadmapItem.progressnumberOptional progress value from 0 to 100; shown in the progress variant.

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"timeline"
itemsYes—

Usage

const roadmapItems: RoadmapItem[] = [
  {
    id: "exports",
    title: "Workspace data exports",
    status: "planned",
    date: "Q2 2027",
    group: "Q2 2027",
    release: "Summer release",
    description: "Plan an export flow for workspace administrators.",
  },
  {
    id: "templates",
    title: "Reusable project templates",
    status: "in-progress",
    progress: 45,
    group: "Q2 2027",
  },
];

<RoadmapSection
  variant="kanban"
  title="Product direction"
  items={roadmapItems}
/>;

The kanban variant groups items by status. Quarter, column, grouped, and release compositions use the supplied group labels; items without one appear under “Other milestones.” Progress values outside the inclusive 0–100 range throw an explicit RangeError.

Accessibility

Status text is visible and does not rely on color alone. Native progress elements are labeled with their milestone title. Horizontal and kanban layouts are keyboard-focusable scrolling regions; grouped milestones use headings and ordered lists.

The section does not infer dates, progress, completion, or release timing.

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 { RoadmapSection } from "@puzzle-ui/pieces";

type RoadmapSectionProps = ComponentProps<typeof RoadmapSection>;

export function CustomizedSection(props: RoadmapSectionProps) {
  return <RoadmapSection {...props} className={[props.className, "brand-section"].filter(Boolean).join(" ")} />;
}

Responsive behavior

Use the preview device selector to review mobile, tablet, and desktop widths. The built-in variant controls section structure; ensure application-provided media, form controls, and children can shrink or wrap without horizontal overflow. Use the existing responsive breakpoints in scoped CSS when the consuming layout needs a product-specific adjustment.

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 { RoadmapSection } from "@puzzle-ui/pieces";

type RoadmapSectionProps = ComponentProps<typeof RoadmapSection>;

export function SectionWrapper(props: RoadmapSectionProps) {
  return <RoadmapSection {...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.