# Code Block

A syntax-styled code block with a language label and copy button.

- Category: AI & Agents
- Page: https://wunderui.com/components/code-block
- Tier: Core and Pro

## Install

Code Block ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { CodeBlock } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { CodeBlock } from "@wunderui/react"

export function Install() {
  return <CodeBlock language="bash" code="npm install @wunderui/react" />
}
```

Expected result: You see a bordered block with the label bash and a Copy button on top, and the command below. Press Copy and it reads Copied for a moment.

## When to use

### Use Code Block for

- A command or a snippet in a doc, a changelog or a setup guide
- Code in an assistant message, between two sentences of the reply
- Short config or JSON that people copy as it is

### Use something else

- [Artifact Panel](https://wunderui.com/components/artifact-panel) for a file the agent made, with versions and a status
- [Diff View](https://wunderui.com/components/diff-view) for a change between two versions of the code
- [Markdown](https://wunderui.com/components/markdown) for prose around the code, with headings, lists and links

## Keyboard

The copy button is a native button, so the browser handles focus and activation. The code area is a focusable region, so its scrolling works from the keyboard.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus between the copy button and the code area of a block, and on to the next block. |
| `Enter` or `Space` | On the copy button: copies the code to the clipboard. |
| `←` or `→` | On the code area: scrolls a long line sideways. |

Focus shows as an indigo border with a 2 px ring on both stops. There is no copy shortcut, but Ctrl+C or Cmd+C copies a text selection as on any page.

## Behavior

What the block does with its code, the clipboard, assistive technology and motion.

- **Plain text:** The code is rendered as text, so whitespace and line breaks are kept and markup shows as characters. There is no syntax highlighting, line numbers or wrapping option.
- **Language:** The language only fills the label and names the code area. Without it the header reads code and the region is named Code code.
- **Wide and tall code:** A line wider than the block does not wrap, and the code area scrolls sideways. The block has no maximum height, so cap long code in the container you put it in.
- **Copy:** The button writes the code to the clipboard and waits for the result. On success it shows the check and Copied for 1.2 seconds, plays the ring pulse, shows the tooltip and calls the callback.
- **When the copy fails:** If the browser refuses the write (no permission, an insecure page, a sandboxed frame), the block shows nothing and skips the callback. Offer your own fallback, such as selecting the text.
- **Live region:** The block has no live region. The confirmation is a tooltip and a change of the button's name, and neither is announced reliably, so what a screen reader says depends on the reader.
- **Focus:** The code area is a named region with a tab stop, so it takes focus and arrow keys scroll it. Each block adds two tab stops.
- **Motion:** The copy icon fades out while it scales down and turns, and the check fades in with a short overshoot. The ring pulse is one slow animation of the shadow.
- **Reduced motion:** With reduced motion the scale and rotation are dropped, so the two icons crossfade, and the ring pulse does not play. The label, check and tooltip still show.

## Anatomy

- `CodeBlock`: The bordered box, clipped to its rounded corners. It takes the code, the language and a copy callback, and keeps its own copy state.
- `Header`: The row above the code, with a bottom border: the language label on the left and the copy button on the right.
- `Language`: The language in small tertiary type. It is a label only and loads no grammar, and without it the label reads code.
- `Copy button`: A native button with an icon and the word Copy. After a successful copy it shows a check and Copied for about a second, with a green ring pulse and a tooltip.
- `Code area`: A scrollable region named after the language, with a tab stop. It scrolls sideways when a line is wider than the block, and arrow keys scroll it once it has focus.
- `Code`: The code, shown verbatim in the foreground colour. Whitespace is kept, nothing is highlighted and lines are not numbered.

## Best practices

### When to use

- Use CodeBlock for a snippet in a message or doc. For a file the agent made use Artifact Panel, and for a change between two versions use Diff View.

### Do

- Always pass the language, such as tsx or bash. It labels the header and names the code area for screen readers, which otherwise hear Code code.
- Use the copy callback for side effects such as analytics. It runs only after the code reached the clipboard, and the block already confirms the copy itself, so add no toast.
- Keep lines short where you can. A wider line scrolls sideways, and the code area is keyboard reachable, so scrolling works without a mouse.

### Don't

- Don't expect syntax highlighting, line numbers, line wrapping or a maximum height. The block shows plain monospace text, scrolls sideways and grows with its lines.
- Don't treat a click on Copy as a copy. If the browser refuses the clipboard, the block shows no confirmation or error and skips the callback, so report a copy as done only from the callback.

## API reference

### CodeBlock

| Prop | Type | Default | Description |
|---|---|---|---|
| code* | string |  | The code to show and to copy, as one string. It is rendered as text, line for line, and copied as it is. |
| actions | React.ReactNode |  | Extra controls rendered in the header, left of the copy button. |
| className | string |  | Extra classes for the outer box, for example `max-w-xl`. The box clips its content to its rounded corners. |
| frame | boolean | true | When false, the block's outer border and rounding are removed for embedding in an already-framed container. |
| language | string |  | The label in the header and the name of the code area (`<language> code`). It loads no grammar. Without it the label reads `code`. |
| maxLines | number |  | When the code has more lines, only the first maxLines are shown; a toggle button reveals the rest. |
| onCopy | () => void |  | Called after the code landed on the clipboard. It is not called when the write is refused. The block already confirms the copy, so use it for side effects only. |
| title | React.ReactNode |  | Content shown in the header instead of the language label. The language still names the code region via aria-label. |
| tone | "default" \| "dark" | "default" | Visual tone of the block. "dark" darkens the container, header, copy button and code text. |

## Examples

### Content: a short command, a line wider than the block, many lines

### Dark tone, title, actions, line limit and diff

## In context

### Copy: onCopy runs only when the code reached the clipboard

Press Copy and watch the count. If the browser refuses the write, nothing is confirmed and the copy callback is not called, so only report a copy as done from that callback.

### Setup: a command, then the code that uses it

Each block has its own label and copy button. Tab reaches the copy button, then the code area, then the next block's copy button.

### Answer: a code block inside an assistant message

The block sits between two sentences of the reply. It is a block of its own, so the reply stays readable when the code is long.

## For AI agents

`get_component("code-block")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
