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.
cards - Give every use case a distinct card.
tabs - Switch between detailed use-case stories.
split - Feature one use case beside supporting stories.
alternating - Alternate media and narrative down the page.
persona - Lead with the persona the workflow serves.
industry - Organize content around an industry audience.
bento - Give a selected use case extra grid space.
featured - Open with a prominent use-case story.
list - Keep descriptions and benefits in a compact list.
editorial - Tell longer use-case stories with generous media.
carousel - Browse a horizontally scrollable set of stories.
categorized - Group related workflows by category.
API
| Prop | Type | Description |
|---|---|---|
variant | UseCasesVariant | Selects one of thirteen compositions; defaults to grid. |
items | readonly UseCaseItem[] | Use-case content with stable id and required title. |
UseCaseItem.persona | string | Optional audience persona shown in persona layouts and searched when filtering. |
UseCaseItem.industry | string | Optional industry label shown in industry layouts and searched when filtering. |
UseCaseItem.category | string | Optional grouping and filter value. |
UseCaseItem.benefits | readonly ReactNode[] | Optional benefit list. |
UseCaseItem.media | ReactNode | Optional image, video, or other consumer-provided media. |
UseCaseItem.action | ReactNode | Optional action supplied by the consumer. |
UseCaseItem.featured | boolean | Emphasizes an item in featured layouts. |
filterable | boolean | Adds a labeled search field and category select when categories exist. Defaults to false. |
| Shared section props | Marketing section props | Semantic 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.
| Prop | Required | Default |
|---|---|---|
variant | No | "grid" |
items | Yes | — |
filterable | No | false |
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.