CaseStudiesSection
Explain client work with challenge, solution, results, media, metrics, and responsive portfolio layouts.
CaseStudiesSection presents client projects with optional industry context, narrative, imagery, measurable outcomes, and native links. A featured case can be selected explicitly or marked in the data.
Beta API maturity: Beta.
Installation
import {
CaseStudiesSection,
type BusinessCaseStudy,
type CaseStudiesSectionVariant,
} from "@puzzle-ui/pieces";Variant previews
Each of the thirteen variants has a separate preview, including a hospitality before-and-after example and SaaS outcome metrics.
grid - Browse case studies in a responsive grid.
featured - Lead with a featured client result.
split - Give the first project additional room.
masonry - Use responsive columns for a varied portfolio.
carousel - Scroll through a focused set of projects.
editorial - Tell each project story with more context.
metrics - Put measurable results front and center.
before-after - Compare the experience before and after.
cards - Separate each project on a card surface.
list - Present projects in a linear reading order.
portfolio - Let project imagery lead the page.
bento - Create a varied portfolio grid.
horizontal - Show projects in a horizontal rail.
API
| Prop | Type | Description |
|---|---|---|
variant | CaseStudiesSectionVariant | grid (default), featured, split, masonry, carousel, editorial, metrics, before-after, cards, list, portfolio, bento, or horizontal. |
items | readonly BusinessCaseStudy[] | Case studies with unique IDs and titles; optional client, industry, challenge, solution, results, image, metrics, and link. |
featuredCase | BusinessCaseStudy | string | Optional case object or ID promoted to the lead position. |
BusinessCaseStudy.beforeAfter | { before, after } | Optional pair of editorial images displayed by the before-after variant. |
BusinessCaseStudy.external | boolean | Opens the case link in a new browsing context with noopener noreferrer. |
| Shared section props | MarketingSectionBaseProps | Heading, actions, root element, native section attributes, 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 | — |
featuredCase | No | — |
Usage
<CaseStudiesSection
variant="metrics"
title="Selected work"
items={[
{
id: "cedar-house",
title: "A more considered guest journey",
client: "Cedar House",
industry: "Hospitality",
challenge: "Connect a fragmented guest experience.",
solution: "Unify booking and on-property service.",
results: "Increase direct bookings and guest satisfaction.",
metrics: [{ id: "bookings", label: "Direct bookings", value: "+28%" }],
href: "https://example.com/work/cedar-house",
external: true,
},
]}
/>Images, accessibility, and rendering
Use descriptive alt text for project images. Missing image sources render an accessible placeholder rather than a broken image. Case studies are semantic articles in a list; challenge, solution, and results use labeled sections, and metrics use a description list. Rails remain keyboard-scrollable and images are lazy-loaded. The component does not fetch case data 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 { CaseStudiesSection } from "@puzzle-ui/pieces";
type CaseStudiesSectionProps = ComponentProps<typeof CaseStudiesSection>;
export function CustomizedSection(props: CaseStudiesSectionProps) {
return <CaseStudiesSection {...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 { CaseStudiesSection } from "@puzzle-ui/pieces";
type CaseStudiesSectionProps = ComponentProps<typeof CaseStudiesSection>;
export function SectionWrapper(props: CaseStudiesSectionProps) {
return <CaseStudiesSection {...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.