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.
two-column - Balance two flexible content slots.
three-column - Arrange three supporting editorial points.
split - Pair the main story with a related sidebar.
image-left - Place supporting media before the copy.
image-right - Place supporting media after the copy.
media - Give an image or media slot equal prominence.
editorial - Use a generous text-and-image composition.
quote - Present supplied copy as a cited quotation.
narrow - Constrain the measure for focused reading.
wide - Give the content a wider page measure.
full-width - Let the section use the available width.
API
| Prop | Type | Description |
|---|---|---|
variant | ContentSectionVariant | single-column (default), two-column, three-column, split, image-left, image-right, media, editorial, quote, narrow, wide, or full-width. |
children | ReactNode | Flexible rich content, rendered without extra per-paragraph wrappers. |
columns | readonly ReactNode[] | Optional content slots for the two- and three-column variants. Each slot is wrapped only for grid layout. |
image | EditorialImage | Optional semantic figure with responsive image data and caption. |
media | ReactNode | Optional custom media slot, such as a video or an existing UI component. Takes precedence over image. |
sidebar | ReactNode | Optional complementary content rendered as an <aside>. |
attribution | string | Optional citation displayed in the quote variant. |
| 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 | "single-column" |
image | No | — |
media | No | — |
columns | No | — |
sidebar | No | — |
attribution | No | — |
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.