Skip to Content

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.

390 × 844

featured - Lead with a featured client result.

390 × 844

split - Give the first project additional room.

390 × 844

masonry - Use responsive columns for a varied portfolio.

390 × 844

carousel - Scroll through a focused set of projects.

390 × 844

editorial - Tell each project story with more context.

390 × 844

metrics - Put measurable results front and center.

390 × 844

before-after - Compare the experience before and after.

390 × 844

cards - Separate each project on a card surface.

390 × 844

list - Present projects in a linear reading order.

390 × 844

portfolio - Let project imagery lead the page.

390 × 844

bento - Create a varied portfolio grid.

390 × 844

horizontal - Show projects in a horizontal rail.

390 × 844

API

PropTypeDescription
variantCaseStudiesSectionVariantgrid (default), featured, split, masonry, carousel, editorial, metrics, before-after, cards, list, portfolio, bento, or horizontal.
itemsreadonly BusinessCaseStudy[]Case studies with unique IDs and titles; optional client, industry, challenge, solution, results, image, metrics, and link.
featuredCaseBusinessCaseStudy | stringOptional 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.externalbooleanOpens the case link in a new browsing context with noopener noreferrer.
Shared section propsMarketingSectionBasePropsHeading, 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.

PropRequiredDefault
variantNo"grid"
itemsYes—
featuredCaseNo—

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.