Skip to Content

UseCasesSection

Explain SaaS workflows with audience details, benefits, media, actions, and optional category filters.

UseCasesSection describes the teams, industries, and workflows a product serves. Each item can include a summary, benefits, media, category, persona or industry label, and a consumer-provided action.

Beta API maturity: Beta.

Installation

import {
  UseCasesSection,
  type UseCaseItem,
} from "@puzzle-ui/pieces";

Variant previews

Each of the thirteen variants is previewed independently with fictional product, operations, and customer-success workflows.

grid - Scan use cases in a balanced grid.

390 × 844

cards - Give every use case a distinct card.

390 × 844

tabs - Switch between detailed use-case stories.

390 × 844

split - Feature one use case beside supporting stories.

390 × 844

alternating - Alternate media and narrative down the page.

390 × 844

persona - Lead with the persona the workflow serves.

390 × 844

industry - Organize content around an industry audience.

390 × 844

bento - Give a selected use case extra grid space.

390 × 844

featured - Open with a prominent use-case story.

390 × 844

list - Keep descriptions and benefits in a compact list.

390 × 844

editorial - Tell longer use-case stories with generous media.

390 × 844

carousel - Browse a horizontally scrollable set of stories.

390 × 844

categorized - Group related workflows by category.

390 × 844

API

PropTypeDescription
variantUseCasesVariantSelects one of thirteen compositions; defaults to grid.
itemsreadonly UseCaseItem[]Use-case content with stable id and required title.
UseCaseItem.personastringOptional audience persona shown in persona layouts and searched when filtering.
UseCaseItem.industrystringOptional industry label shown in industry layouts and searched when filtering.
UseCaseItem.categorystringOptional grouping and filter value.
UseCaseItem.benefitsreadonly ReactNode[]Optional benefit list.
UseCaseItem.mediaReactNodeOptional image, video, or other consumer-provided media.
UseCaseItem.actionReactNodeOptional action supplied by the consumer.
UseCaseItem.featuredbooleanEmphasizes an item in featured layouts.
filterablebooleanAdds a labeled search field and category select when categories exist. Defaults to false.
Shared section propsMarketing section propsSemantic root element, header, theme, native 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—
filterableNofalse

Usage

const useCases: UseCaseItem[] = [
  {
    id: "launch",
    title: "Plan a product launch",
    persona: "Product manager",
    industry: "Software",
    category: "Planning",
    description: "Coordinate decisions, owners, and milestones.",
    benefits: ["Align work across teams", "Make dependencies visible"],
    media: <img src="/launch.png" alt="Product launch plan with milestones" />,
    action: <a href="/workflows/launch">Explore the workflow</a>,
  },
];

<UseCasesSection
  variant="tabs"
  title="Workflows by team"
  items={useCases}
  filterable
/>;

Filtering searches the title, category, persona, industry, and plain-text description. Rich React descriptions are not searched. When no items match, the section presents a status message instead of an empty list.

Accessibility

Tabs use the keyboard-operable UI Tabs primitive. Search and category controls have visible labels, carousel content is a native horizontal scroller, and benefit lists retain list semantics. Supply meaningful alternative text for informative media and ensure action nodes have accessible names.

The section does not infer a product's target audience or outcomes; all claims and actions come from the supplied data.

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

type UseCasesSectionProps = ComponentProps<typeof UseCasesSection>;

export function CustomizedSection(props: UseCasesSectionProps) {
  return <UseCasesSection {...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 { UseCasesSection } from "@puzzle-ui/pieces";

type UseCasesSectionProps = ComponentProps<typeof UseCasesSection>;

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