BlogSection
Present editorial articles with responsive grids, featured stories, bylines, categories, and reading details.
BlogSection renders consumer-provided article data as semantic article cards. Choose from responsive grids, lists, editorial feature layouts, category groups, and horizontal rails.
Beta API maturity: Beta.
Installation
import {
BlogSection,
type BlogArticle,
type BlogSectionVariant,
} from "@puzzle-ui/pieces";Variant previews
Each of the thirteen variants has its own preview. The examples use fictional Morrow Journal stories, authors, dates, and photographs.
grid - Browse recent stories in a responsive card grid.
featured - Lead with one article and keep supporting stories nearby.
list - Give each article a readable, full-width row.
masonry - Use a responsive editorial column layout.
carousel - Scroll through a compact horizontal story rail.
editorial - Give the leading story more room and a clear byline.
magazine - Pair a cover story with supporting articles.
split - Separate the lead story from the supporting list.
compact - Show article summaries in a denser list.
categories - Group articles under their editorial categories.
latest - Put the newest lead story first.
horizontal - Present a free-scrolling row of articles.
cards - Place article content on distinct card surfaces.
API
| Prop | Type | Description |
|---|---|---|
variant | BlogSectionVariant | grid (default), featured, list, masonry, carousel, editorial, magazine, split, compact, categories, latest, horizontal, or cards. |
items | readonly BlogArticle[] | Article data. Each article needs a stable, unique id and title. |
featuredArticle | BlogArticle | Optional lead article; it replaces an item with the same ID rather than duplicating it. |
BlogArticle.excerpt | string | Optional short summary. |
BlogArticle.image | EditorialImage | Optional responsive image, alt text, dimensions, loading preference, and caption. |
BlogArticle.author | EditorialAuthor | Optional author name, link, and decorative portrait. |
BlogArticle.date | string | Optional date string. A valid date is formatted in UTC and exposed with a <time> element. |
BlogArticle.category | string | Optional category label; the categories variant groups by this value. |
BlogArticle.readingTime | string | number | Optional reading-time label; numeric values are rendered in minutes. |
BlogArticle.href | string | Optional native link for the article title. |
BlogArticle.featured | boolean | Marks the article used by featured layouts when featuredArticle is not supplied. |
| 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 | "grid" |
items | Yes | — |
featuredArticle | No | — |
Usage
const articles: BlogArticle[] = [
{
id: "slow-mornings",
title: "The case for slower mornings",
excerpt: "Small rituals can change the pace of a working day.",
image: {
src: "/journal/slow-mornings.jpg",
alt: "Morning light across a quiet studio",
width: 1200,
height: 800,
caption: "The studio before the day begins.",
},
author: { name: "Mara Chen", href: "/journal/authors/mara-chen" },
date: "2025-05-12",
category: "Studio notes",
readingTime: 6,
href: "/journal/slow-mornings",
featured: true,
},
];
<BlogSection
variant="featured"
eyebrow="Morrow Journal"
title="Notes for more considered days"
items={articles}
/>;The masonry composition uses responsive CSS columns. carousel and horizontal use a native, focusable horizontal scroll rail. Article order is supplied by the application; the latest variant emphasizes the first article and does not sort data.
Images and editorial data
An article image may include src, descriptive alt, intrinsic width and height, loading, and an optional caption. Article images are lazy-loaded by default. If an image object has no usable source, the section shows an accessible placeholder. Authors, dates, categories, and reading time remain independent optional fields.
Accessibility and rendering
Articles are list items containing semantic <article> elements and level-three headings. Give informative photos concise alt text and decorative images an empty alt. Dates use <time>; links remain native anchors. The component does not fetch or sort stories and renders 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 { BlogSection } from "@puzzle-ui/pieces";
type BlogSectionProps = ComponentProps<typeof BlogSection>;
export function CustomizedSection(props: BlogSectionProps) {
return <BlogSection {...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 { BlogSection } from "@puzzle-ui/pieces";
type BlogSectionProps = ComponentProps<typeof BlogSection>;
export function SectionWrapper(props: BlogSectionProps) {
return <BlogSection {...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.