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.
quarters - Arrange milestones into quarter-like groups.
columns - Lay out custom groups as scrolling columns.
cards - Give each roadmap item a distinct card.
list - Keep dates and status in a compact list.
progress - Show only the progress values supplied for items.
horizontal - Scroll milestones along a horizontal timeline.
vertical - Use a simple vertical sequence without card chrome.
grouped - Separate items with headings for their groups.
kanban - Group items into columns by status.
milestones - Number ordered milestones along a connector.
release - Group milestones by their supplied release label.
API
| Prop | Type | Description |
|---|---|---|
variant | RoadmapVariant | Selects one of twelve compositions; defaults to timeline. |
items | readonly 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.statusLabel | ReactNode | Optional consumer-provided status label. |
RoadmapItem.date | ReactNode | Optional date or date label. |
RoadmapItem.group | string | Optional group used by grouped, quarter, and column variants. |
RoadmapItem.release | string | Optional release label used by the release variant. |
RoadmapItem.description | ReactNode | Optional milestone description. |
RoadmapItem.progress | number | Optional 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.
| Prop | Required | Default |
|---|---|---|
variant | No | "timeline" |
items | Yes | — |
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.