Skip to Content

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.

390 × 844

list - Keep release details in a straightforward list.

390 × 844

cards - Separate releases into responsive cards.

390 × 844

grouped - Group releases by the supplied release group.

390 × 844

versioned - Give version numbers a prominent position.

390 × 844

featured - Lead with one featured release.

390 × 844

compact - Show a concise release history.

390 × 844

release-notes - Use an open, document-like notes layout.

390 × 844

categories - Organize releases by their primary change category.

390 × 844

split - Separate the latest release from supporting notes.

390 × 844

vertical - Stack releases in a vertical chronology.

390 × 844

horizontal - Browse release cards along a horizontal rail.

390 × 844

API

PropTypeDescription
variantChangelogSectionVarianttimeline (default), list, cards, grouped, versioned, featured, compact, release-notes, categories, split, vertical, or horizontal.
itemsreadonly ChangelogRelease[]Release data with stable, unique IDs and required version strings.
featuredReleaseChangelogReleaseOptional lead release; it replaces a collection item with the same ID.
ChangelogRelease.datestringOptional valid date, formatted in UTC and exposed with <time>.
ChangelogRelease.typestringOptional release type label, such as Feature release, Minor, or Patch.
ChangelogRelease.descriptionReactNodeOptional release summary.
ChangelogRelease.categoriesreadonly ChangelogCategory[]Optional change groups with names and rich change entries.
ChangelogRelease.hrefstringOptional native link on the version heading.
ChangelogRelease.featuredbooleanMarks a release for featured layouts when featuredRelease is not provided.
ChangelogRelease.groupstringOptional group heading. grouped uses this value or the UTC year of the date.
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"timeline"
itemsYes—
featuredReleaseNo—

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.