Skip to content
Browse documentation
whisk/ui

CodeBlock

Show multi-line source, commands, and output in a readable surface.

Overview

CodeBlock presents multi-line source, commands, and output in a readable surface. It keeps source plain by default; copying and syntax preparation are explicit choices.

Use when

Readers need to inspect or copy multi-line code or a command sequence.

Use instead

Use Code inside a sentence for a short identifier or command.

Usage

export const retries = 3;
import { CodeBlock } from "@smoothie-framework/whisk-react";

<CodeBlock
  code="export const retries = 3;"
  contentLabel="Retry configuration"
/>

Examples

Sizes

Use size to choose the density of the code surface.

const small = true;
const medium = true;
const large = true;
import { CodeBlock, Stack } from "@smoothie-framework/whisk-react";

<Stack gap={3}>
  <CodeBlock size="sm" code="const small = true;" contentLabel="Small code" />
  <CodeBlock size="md" code="const medium = true;" contentLabel="Medium code" />
  <CodeBlock size="lg" code="const large = true;" contentLabel="Large code" />
</Stack>

Syntax highlighting

Install the optional highlighter with bun add @smoothie-framework/whisk-core, then prepare the source before passing it to CodeBlock.

const ready = true;
const message = <Text color="accent">Ready</Text>;
import { highlightCodeBlock } from "@smoothie-framework/whisk-core/code-block/highlight";
import { CodeBlock } from "@smoothie-framework/whisk-react";

const code = highlightCodeBlock('const ready = true;\nconst message = <Text color="accent">Ready</Text>;', "tsx");

<CodeBlock code={code} contentLabel="Ready message source" />

Title

Use CodeBlock.Title in a header to identify a file, language, or command. It is visible metadata, not the code region's accessible name.

config.ts
export const retries = 3;
import { CodeBlock } from "@smoothie-framework/whisk-react";

<CodeBlock code="export const retries = 3;" header={<CodeBlock.Title>config.ts</CodeBlock.Title>} contentLabel="Configuration source" />

Copy button

Place CopyTrigger in an inline control when it belongs beside the title. Copying is optional and the button announces its state.

bash
bun run typecheck
import { CodeBlock } from "@smoothie-framework/whisk-react";

<CodeBlock.Root code="bun run typecheck">
  <CodeBlock.Header>
    <CodeBlock.Title>bash</CodeBlock.Title>
    <CodeBlock.Control placement="inline"><CodeBlock.CopyTrigger /></CodeBlock.Control>
  </CodeBlock.Header>
  <CodeBlock.Content aria-label="Typecheck command" />
</CodeBlock.Root>

Line numbers

Use line numbers when readers need to refer to a specific source line. Line numbers are 1-based.

const retries = 3;
const timeout = 5_000;
import { CodeBlock } from "@smoothie-framework/whisk-react";

<CodeBlock code={"const retries = 3;\nconst timeout = 5_000;"} contentLabel="Retry configuration" showLineNumbers />

Line highlighting

Use highlightLines to call attention to specific 1-based source lines without changing the copied text.

export const retries = 3;
export const timeout = 5_000;
export const telemetry = false;
import { CodeBlock } from "@smoothie-framework/whisk-react";

const source = "export const retries = 3;\nexport const timeout = 5_000;\nexport const telemetry = false;";

<CodeBlock code={source} contentLabel="Configuration source" highlightLines={[2]} />

Line focus

Use focusedLineNumbers to emphasize the relevant 1-based source lines and dim the others.

export const retries = 3;
export const timeout = 5_000;
export const telemetry = false;
import { CodeBlock } from "@smoothie-framework/whisk-react";

const source = "export const retries = 3;\nexport const timeout = 5_000;\nexport const telemetry = false;";

<CodeBlock code={source} contentLabel="Configuration source" focusedLineNumbers={[2]} />

Diff

Use addedLineNumbers and removedLineNumbers to annotate a source diff. Do not rely on color alone to explain the change.

const endpoint = "/v1/projects";
const timeout = 5_000;
const timeout = 10_000;
export { endpoint, timeout };
import { CodeBlock } from "@smoothie-framework/whisk-react";

const source = "const endpoint = \"/v1/projects\";\nconst timeout = 5_000;\nconst timeout = 10_000;\nexport { endpoint, timeout };";

<CodeBlock code={source} contentLabel="Endpoint change" showLineNumbers addedLineNumbers={[3]} removedLineNumbers={[2]} />

Floating copy button

Pass controls to the convenience component to place the copy button over the source.

bun run typecheck
import { CodeBlock } from "@smoothie-framework/whisk-react";

<CodeBlock code="bun run typecheck" contentLabel="Typecheck command" controls={<CodeBlock.CopyTrigger />} />

Wrap overflow

Use wrap when keeping a long line visible matters more than preserving its horizontal shape. The original source is still copied unchanged.

const release = {
  endpoint: "https://api.example.com/v1/workspaces/continuous-delivery/releases?include=checks,artifacts,reviewers",
  retries: 3,
};
import { CodeBlock } from "@smoothie-framework/whisk-react";

const source = "const release = {\n  endpoint: \"https://api.example.com/v1/workspaces/continuous-delivery/releases?include=checks,artifacts,reviewers\",\n  retries: 3,\n};";

<CodeBlock code={source} contentLabel="Release request" wrap />

Line numbers with word wrap

Combine showLineNumbers and wrap when readers need both stable references and complete long lines.

const release = {
  endpoint: "https://api.example.com/v1/workspaces/continuous-delivery/releases?include=checks,artifacts,reviewers",
  retries: 3,
};
import { CodeBlock } from "@smoothie-framework/whisk-react";

const source = "const release = {\n  endpoint: \"https://api.example.com/v1/workspaces/continuous-delivery/releases?include=checks,artifacts,reviewers\",\n  retries: 3,\n};";

<CodeBlock code={source} contentLabel="Release request" showLineNumbers wrap />

Props

Component props

PropTypeDefaultDescription
codestring | PreparedCodeBlocknonePass the exact source, or a PreparedCodeBlock returned by highlightCodeBlock. Syntax highlighting is opt-in: install @smoothie-framework/whisk-core and import the helper from its code-block/highlight entry.
header | controlsReactNodenoneUse CodeBlock.Title in a header and CodeBlock.CopyTrigger in controls when those affordances help readers.
contentLabelstringCode contentGive the focusable code region a clear accessible name when surrounding context does not already identify it.
sizesm | md | lgmdChoose the density of the code surface.
showLineNumbersbooleanfalseAdd 1-based line numbers when readers need to reference a source location.
wrapbooleanfalseWrap long lines instead of requiring horizontal scrolling. The copied source is unchanged.
highlightLines | focusedLineNumbersreadonly number[]noneHighlight or focus existing 1-based source lines without changing the source text.
addedLineNumbers | removedLineNumbersreadonly number[]noneMark existing 1-based source lines as added or removed. A line cannot be both. With showLineNumbers, the gutter shows + and −; add nearby prose for the change because no screen-reader change text is added.
CodeBlock.Control placementinline | floatingfloatingPlace authored controls beside the header or over the code surface. The convenience controls prop uses floating placement.
CodeBlock.Root | Header | Title | Control | Content | CopyTriggercompound partsnoneUse the explicit parts when the header or controls need a custom authored order or placement.

Shared props

PropSupportedNotes
as / asChildNoCodeBlock owns its preformatted structure.
Style propsYesUse the shared static style-prop surface on the root. See Style props.
className / styleYesApplied to the root host.
refYesForwards to the root host.
Native HTML attributesYesNative root attributes are forwarded.

Accessibility

CodeBlock escapes its source and never executes it. The code region receives keyboard focus so people can scroll it; provide contentLabel when nearby text does not identify the source. CodeBlock.Title is visible metadata, not an accessible label for the region. CopyTrigger is optional and announces its copying, copied, or failed state through its accessible name. Diff lines use + and − only with showLineNumbers; they do not receive screen-reader change text, so describe the change in adjacent prose. Keep long source usable at browser zoom.