Skip to Content

ContentSection

Compose semantic editorial content with flexible columns, media, image placement, quotations, and optional sidebars.

ContentSection is a flexible layout for application-owned rich content. Supply regular React children, content columns, media, a figure, and an optional related-content sidebar.

Beta API maturity: Beta.

Installation

import {
  ContentSection,
  type ContentSectionVariant,
} from "@puzzle-ui/pieces";

Variant previews

Every variant has an independent preview using a fictional Morrow studio story and real editorial imagery.

single-column - Keep long-form copy in one readable flow.

390 × 844

two-column - Balance two flexible content slots.

390 × 844

three-column - Arrange three supporting editorial points.

390 × 844

split - Pair the main story with a related sidebar.

390 × 844

image-left - Place supporting media before the copy.

390 × 844

image-right - Place supporting media after the copy.

390 × 844

media - Give an image or media slot equal prominence.

390 × 844

editorial - Use a generous text-and-image composition.

390 × 844

quote - Present supplied copy as a cited quotation.

390 × 844

narrow - Constrain the measure for focused reading.

390 × 844

wide - Give the content a wider page measure.

390 × 844

full-width - Let the section use the available width.

390 × 844

API

PropTypeDescription
variantContentSectionVariantsingle-column (default), two-column, three-column, split, image-left, image-right, media, editorial, quote, narrow, wide, or full-width.
childrenReactNodeFlexible rich content, rendered without extra per-paragraph wrappers.
columnsreadonly ReactNode[]Optional content slots for the two- and three-column variants. Each slot is wrapped only for grid layout.
imageEditorialImageOptional semantic figure with responsive image data and caption.
mediaReactNodeOptional custom media slot, such as a video or an existing UI component. Takes precedence over image.
sidebarReactNodeOptional complementary content rendered as an <aside>.
attributionstringOptional citation displayed in the quote variant.
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"single-column"
imageNo—
mediaNo—
columnsNo—
sidebarNo—
attributionNo—

Usage

<ContentSection
  variant="image-right"
  eyebrow="Our point of view"
  title="Objects with a longer story"
  description="Thoughtful design starts with what we choose to keep."
  image={{
    src: "/stories/materials.jpg",
    alt: "Natural materials arranged on a studio worktable",
    width: 1200,
    height: 800,
    caption: "A selection of materials in the Morrow studio.",
  }}
  sidebar={<a href="/about/materials">How we choose materials</a>}
>
  <p>
    Useful things can be beautiful without asking for attention. We design
    objects to be repaired, shared, and kept for a long time.
  </p>
</ContentSection>;

For custom media, provide media={<video ... />} instead of image. Column slots are useful for short, independent blocks; use ordinary children for long-form copy. The quote variant wraps supplied children in a <blockquote> and renders the optional attribution in <cite>.

Accessibility and responsive behavior

The section uses semantic <section>, <figure>, <figcaption>, <blockquote>, <cite>, and <aside> elements where appropriate. Set meaningful image alternatives and keep heading levels in sequence with the surrounding page. Two- and three-column layouts collapse at narrow widths; the sidebar and custom media stay in normal document flow. Content is supplied by the application and is server-renderable.

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 { ContentSection } from "@puzzle-ui/pieces";

type ContentSectionProps = ComponentProps<typeof ContentSection>;

export function CustomizedSection(props: ContentSectionProps) {
  return <ContentSection {...props} className={[props.className, "brand-section"].filter(Boolean).join(" ")} />;
}

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 { ContentSection } from "@puzzle-ui/pieces";

type ContentSectionProps = ComponentProps<typeof ContentSection>;

export function SectionWrapper(props: ContentSectionProps) {
  return <ContentSection {...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.