Skip to Content

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.

390 × 844

tabs - Switch between named code examples.

390 × 844

split - Place snippets side by side when space allows.

390 × 844

editor - Frame code in a lightweight editor-style surface.

390 × 844

terminal - Give command-line examples a terminal treatment.

390 × 844

multi-language - Switch examples by their language label.

390 × 844

numbered - Show readable line numbers beside code.

390 × 844

comparison - Compare code snippets in aligned panels.

390 × 844

installation - Present setup commands as ordered steps.

390 × 844

playground - Edit plain text code in a native textarea.

390 × 844

featured - Emphasize one primary snippet and list supporting samples.

390 × 844

compact - Keep short snippets in a dense presentation.

390 × 844

API

PropTypeDescription
variantCodeShowcaseVariantSelects one of twelve compositions; defaults to single.
itemsreadonly CodeSnippet[]Snippets with stable id, language, and code.
CodeSnippet.titlestringOptional tab label and snippet heading.
CodeSnippet.filenamestringOptional filename or command context.
CodeSnippet.highlightedLinesreadonly number[]Optional 1-based line emphasis; this is presentation only, not syntax highlighting.
copyablebooleanShows a copy action; defaults to true.
showLineNumbersbooleanOverrides line numbering; the numbered variant enables it by default.
editablebooleanEnables the plain-text editor surface; playground enables it by default.
onCopy(code: string) => voidCalled after a successful copy.
onCopyError(error: unknown) => voidReceives 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.

PropRequiredDefault
variantNo"single"
itemsYes—
copyableNotrue
showLineNumbersNo—
editableNo—
onCopyNo—
onCopyErrorNo—

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.