ProductShowcaseSection
Present SaaS product screens in responsive layouts with device frames, annotations, tabs, and carousels.
ProductShowcaseSection presents consumer-provided product media and supporting copy. Its layouts range from single-screen browser and device frames to interactive tabs, galleries, and a controlled carousel.
Beta API maturity: Beta.
Installation
import {
ProductShowcaseSection,
type ProductShowcaseItem,
} from "@puzzle-ui/pieces";Variant previews
Every layout below is rendered in its own preview, with the same realistic Northstar workspace data so the composition differences are easy to compare.
split - Pair the product view with its explanation.
centered - Center a focused, media-led product story.
browser - Frame a web application screenshot as a browser window.
desktop - Present a wide desktop application view.
mobile - Focus on a responsive mobile screen.
device-stack - Layer a small set of mobile product screens.
gallery - Show several product screens in a gallery.
tabs - Let visitors switch between product capabilities.
carousel - Browse product screens with explicit controls.
sticky - Keep the selected product view beside a feature list.
bento - Give a highlighted capability more room in a grid.
full-width - Use a wider section for expansive product media.
layered - Stack related screens into a layered composition.
editorial - Tell a product story with alternating media and copy.
video - Show a customer-provided video or demo clip.
interactive - Expose annotated product details as disclosures.
API reference
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
items | readonly ProductShowcaseItem[] | Yes | — | Screens or recordings to display; IDs must be unique. |
variant | ProductShowcaseVariant | No | split | Presentation layout. |
| Shared section props | MarketingSectionBaseProps | No | — | Header, root element, width/theme, native attributes, actions, and children. |
ProductShowcaseSectionProps<C> combines the shared section props with
variant and items. The item data model is:
| Property | Type | Description |
|---|---|---|
items | readonly ProductShowcaseItem[] | Product screens and their accompanying content. |
ProductShowcaseItem.id | string | Stable, unique item ID; required by tabs and lists. |
ProductShowcaseItem.title | ReactNode | Item heading and default browser-frame label. |
ProductShowcaseItem.media | ReactNode | Consumer-provided screenshot, video, or other media. |
ProductShowcaseItem.frame | "none" | "browser" | "desktop" | "mobile" | Optional frame override for an item. |
ProductShowcaseItem.caption | ReactNode | Optional media caption. |
ProductShowcaseItem.annotations | readonly ProductShowcaseAnnotation[] | Optional native disclosure annotations. |
ProductShowcaseItem.description | ReactNode | Supporting product explanation. |
ProductShowcaseItem.action | ReactNode | Optional action supplied by the consumer. |
ProductShowcaseItem.featured | boolean | Emphasizes an item in layouts that support a featured item. |
variant defaults to split. Shared section props include the semantic root element, header content, section theme, native attributes, and children.
Usage
const items: ProductShowcaseItem[] = [
{
id: "workspace",
title: "Keep launches in view",
description: "See owners, milestones, and decisions together.",
media: <img src="/screens/launch.png" alt="Launch dashboard with milestones" />,
caption: "Launch dashboard",
annotations: [
{
id: "owners",
label: "Owners",
description: "Review the person responsible for each milestone.",
},
],
},
{
id: "workflows",
title: "Bring context together",
media: <img src="/screens/workflows.png" alt="Workflow builder screen" />,
},
];
<ProductShowcaseSection
variant="tabs"
title="A clear view from brief to launch"
items={items}
/>;browser, desktop, and mobile apply a default frame to each item. An item's frame can override that default. The carousel variant has explicit previous/next buttons and does not auto-advance. The interactive variant renders annotations as native <details> disclosures.
Accessibility
Provide meaningful alternative text for informative screenshots and captions where they add context. Decorative media should use an empty alternative. Tabs use the UI package's keyboard-operable Tabs; the carousel buttons have accessible names and disabled states. Annotation disclosures use native keyboard behavior.
The component does not fetch, create, or infer screenshots. It is server-renderable and does not access browser APIs during render.
Responsive behavior and theme support
Device frames remain within the section width, galleries and split layouts reflow on mobile, and the carousel uses its explicit previous/next controls. Use the Preview device selector to check each layout at mobile, tablet, and desktop widths.
The section consumes semantic Puzzle Theme tokens. Wrap it in Theme or a
scoped theme to inherit the application's palette and typography; use
className for local customization instead of hard-coding theme colors.
Related components
- Video Section for playable product films.
- Product Gallery for retail imagery.
- Features Section for capability descriptions.
- Framework integration for Next.js and TanStack Start.
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 { ProductShowcaseSection } from "@puzzle-ui/pieces";
type ProductShowcaseSectionProps = ComponentProps<typeof ProductShowcaseSection>;
export function CustomizedSection(props: ProductShowcaseSectionProps) {
return <ProductShowcaseSection {...props} className={[props.className, "brand-section"].filter(Boolean).join(" ")} />;
}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 { ProductShowcaseSection } from "@puzzle-ui/pieces";
type ProductShowcaseSectionProps = ComponentProps<typeof ProductShowcaseSection>;
export function SectionWrapper(props: ProductShowcaseSectionProps) {
return <ProductShowcaseSection {...props} />;
}