CodeShowcaseSection
Present copyable SaaS integration snippets with accessible tabs, optional line numbers, and a lightweight editable playground.
CodeShowcaseSection renders consumer-provided code as plain text with optional language tabs, line numbers, highlighted lines, and a copy action. It adds no code editor dependency and does not execute snippets.
Beta API maturity: Beta.
Installation
import {
CodeShowcaseSection,
type CodeSnippet,
} from "@puzzle-ui/pieces";Variant previews
Each variant has a standalone preview. Copy buttons and language tabs are interactive, and the playground uses a native <textarea>.
single - Show one focused code sample.
tabs - Switch between named code examples.
split - Place snippets side by side when space allows.
editor - Frame code in a lightweight editor-style surface.
terminal - Give command-line examples a terminal treatment.
multi-language - Switch examples by their language label.
numbered - Show readable line numbers beside code.
comparison - Compare code snippets in aligned panels.
installation - Present setup commands as ordered steps.
playground - Edit plain text code in a native textarea.
featured - Emphasize one primary snippet and list supporting samples.
compact - Keep short snippets in a dense presentation.
API
| Prop | Type | Description |
|---|---|---|
variant | CodeShowcaseVariant | Selects one of twelve compositions; defaults to single. |
items | readonly CodeSnippet[] | Snippets with stable id, language, and code. |
CodeSnippet.title | string | Optional tab label and snippet heading. |
CodeSnippet.filename | string | Optional filename or command context. |
CodeSnippet.highlightedLines | readonly number[] | Optional 1-based line emphasis; this is presentation only, not syntax highlighting. |
copyable | boolean | Shows a copy action; defaults to true. |
showLineNumbers | boolean | Overrides line numbering; the numbered variant enables it by default. |
editable | boolean | Enables the plain-text editor surface; playground enables it by default. |
onCopy | (code: string) => void | Called after a successful copy. |
onCopyError | (error: unknown) => void | Receives clipboard errors so the consumer can handle them. |
The single variant requires exactly one snippet and throws a RangeError if more are supplied.
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 | "single" |
items | Yes | — |
copyable | No | true |
showLineNumbers | No | — |
editable | No | — |
onCopy | No | — |
onCopyError | No | — |
Usage
const snippets: CodeSnippet[] = [
{
id: "typescript",
title: "Load project data",
language: "typescript",
filename: "projects.ts",
code: [
'const response = await fetch("/api/projects");',
"if (!response.ok) throw new Error(\"Request failed\");",
"const projects = await response.json();",
].join("\n"),
highlightedLines: [2],
},
{
id: "shell",
title: "Request project data",
language: "bash",
code: 'curl -H "Accept: application/json" /api/projects',
},
];
<CodeShowcaseSection
variant="multi-language"
title="Use the projects endpoint"
items={snippets}
/>;The component copies the current editor contents when editable. If the Clipboard API is unavailable or rejects the request, an inline live status explains that manual copying is available. Syntax highlighting is intentionally not included; use a separate code-rendering component when syntax tokenization is required.
Accessibility
Tabs use the keyboard-operable UI Tabs primitive. Copy buttons have accessible names and report success or failure through a live status. Line numbers are hidden from assistive technology while the code remains readable as text. The playground is a labeled native textarea and does not evaluate code.
The component is server-renderable and does not access the clipboard until a user activates the copy button.
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 { CodeShowcaseSection } from "@puzzle-ui/pieces";
type CodeShowcaseSectionProps = ComponentProps<typeof CodeShowcaseSection>;
export function CustomizedSection(props: CodeShowcaseSectionProps) {
return <CodeShowcaseSection {...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 { CodeShowcaseSection } from "@puzzle-ui/pieces";
type CodeShowcaseSectionProps = ComponentProps<typeof CodeShowcaseSection>;
export function SectionWrapper(props: CodeShowcaseSectionProps) {
return <CodeShowcaseSection {...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.