Skip to Content

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.

390 × 844

featured - Lead with one article and keep supporting stories nearby.

390 × 844

list - Give each article a readable, full-width row.

390 × 844

masonry - Use a responsive editorial column layout.

390 × 844

carousel - Scroll through a compact horizontal story rail.

390 × 844

editorial - Give the leading story more room and a clear byline.

390 × 844

magazine - Pair a cover story with supporting articles.

390 × 844

split - Separate the lead story from the supporting list.

390 × 844

compact - Show article summaries in a denser list.

390 × 844

categories - Group articles under their editorial categories.

390 × 844

latest - Put the newest lead story first.

390 × 844

horizontal - Present a free-scrolling row of articles.

390 × 844

cards - Place article content on distinct card surfaces.

390 × 844

API

PropTypeDescription
variantBlogSectionVariantgrid (default), featured, list, masonry, carousel, editorial, magazine, split, compact, categories, latest, horizontal, or cards.
itemsreadonly BlogArticle[]Article data. Each article needs a stable, unique id and title.
featuredArticleBlogArticleOptional lead article; it replaces an item with the same ID rather than duplicating it.
BlogArticle.excerptstringOptional short summary.
BlogArticle.imageEditorialImageOptional responsive image, alt text, dimensions, loading preference, and caption.
BlogArticle.authorEditorialAuthorOptional author name, link, and decorative portrait.
BlogArticle.datestringOptional date string. A valid date is formatted in UTC and exposed with a <time> element.
BlogArticle.categorystringOptional category label; the categories variant groups by this value.
BlogArticle.readingTimestring | numberOptional reading-time label; numeric values are rendered in minutes.
BlogArticle.hrefstringOptional native link for the article title.
BlogArticle.featuredbooleanMarks the article used by featured layouts when featuredArticle is not supplied.
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"grid"
itemsYes—
featuredArticleNo—

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.