ChangelogSection
Publish versioned release notes with dates, release types, change categories, featured updates, and grouping.
ChangelogSection formats application-owned release data as a timeline, list, cards, grouped notes, or featured release. It does not fetch updates or interpret semantic-version ordering.
Beta API maturity: Beta.
Installation
import {
ChangelogSection,
type ChangelogCategory,
type ChangelogRelease,
type ChangelogSectionVariant,
} from "@puzzle-ui/pieces";Variant previews
All twelve variants have their own preview. The examples use fictional Morrow workspace releases with versions, dates, release types, and categorized changes.
timeline - Connect releases along a chronological line.
list - Keep release details in a straightforward list.
cards - Separate releases into responsive cards.
grouped - Group releases by the supplied release group.
versioned - Give version numbers a prominent position.
featured - Lead with one featured release.
compact - Show a concise release history.
release-notes - Use an open, document-like notes layout.
categories - Organize releases by their primary change category.
split - Separate the latest release from supporting notes.
vertical - Stack releases in a vertical chronology.
horizontal - Browse release cards along a horizontal rail.
API
| Prop | Type | Description |
|---|---|---|
variant | ChangelogSectionVariant | timeline (default), list, cards, grouped, versioned, featured, compact, release-notes, categories, split, vertical, or horizontal. |
items | readonly ChangelogRelease[] | Release data with stable, unique IDs and required version strings. |
featuredRelease | ChangelogRelease | Optional lead release; it replaces a collection item with the same ID. |
ChangelogRelease.date | string | Optional valid date, formatted in UTC and exposed with <time>. |
ChangelogRelease.type | string | Optional release type label, such as Feature release, Minor, or Patch. |
ChangelogRelease.description | ReactNode | Optional release summary. |
ChangelogRelease.categories | readonly ChangelogCategory[] | Optional change groups with names and rich change entries. |
ChangelogRelease.href | string | Optional native link on the version heading. |
ChangelogRelease.featured | boolean | Marks a release for featured layouts when featuredRelease is not provided. |
ChangelogRelease.group | string | Optional group heading. grouped uses this value or the UTC year of the date. |
| 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 | "timeline" |
items | Yes | — |
featuredRelease | No | — |
Usage
const releases: ChangelogRelease[] = [
{
id: "2-4",
version: "2.4.0",
date: "2025-05-12",
type: "Feature release",
description: "A more focused workspace for thoughtful collaboration.",
categories: [
{
name: "New",
changes: ["Editorial collections now support shared review."],
},
{
name: "Improved",
changes: ["Keyboard navigation is more consistent."],
},
],
href: "/releases/2.4.0",
group: "Spring 2025",
featured: true,
},
];
<ChangelogSection
variant="grouped"
title="What's new"
items={releases}
/>;grouped groups releases by the explicit group value, falling back to the date's UTC year and then Undated. categories groups each release by its first category, or under Other changes. The supplied order is preserved in every variant; provide releases in the order you want to show.
Accessibility and rendering
Releases and change entries use semantic ordered lists, with headings for versions and groups. Dates use <time>, release types are text labels, and version links remain native anchors. Horizontal notes are keyboard-focusable scroll regions. Dates are validated during rendering; malformed values raise a RangeError. The component is server-renderable and does not fetch release data.
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 { ChangelogSection } from "@puzzle-ui/pieces";
type ChangelogSectionProps = ComponentProps<typeof ChangelogSection>;
export function CustomizedSection(props: ChangelogSectionProps) {
return <ChangelogSection {...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 { ChangelogSection } from "@puzzle-ui/pieces";
type ChangelogSectionProps = ComponentProps<typeof ChangelogSection>;
export function SectionWrapper(props: ChangelogSectionProps) {
return <ChangelogSection {...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.