# Code Block

A scrollable code container with header, copy button, line numbers, and highlighted lines.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<DocsBaseSwitcher base="web" component="code-block" />

<ComponentPreview name="code-block" title="code-block.tsx" align="start" previewClassName="h-auto">
<CodeBlockDemo />
</ComponentPreview>

Code Block renders a monospaced code surface with optional header, copy button, line numbers, and per-line variants for diffs.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add code-block
```
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the following dependencies:
</Step>

```bash
npm install class-variance-authority lucide-react
```

<Step>
Install the required registry components first:
</Step>

```bash
npx frakment add button
```

<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="code-block" title="components/ui/code-block.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx title="example.tsx"
import { CodeBlock, CodeBlockContent } from "@/components/ui/code-block";
```

```tsx title="codeblock.tsx"
<CodeBlock>
  <CodeBlockContent>npm install frakment</CodeBlockContent>
</CodeBlock>
```

## Basic [#basic]

The simplest form — pass a string as children of `CodeBlockContent`.

<ComponentPreview name="code-block-basic" title="code-block-basic.tsx" src="examples/code-block-basic.tsx">
<CodeBlockBasicDemo />
</ComponentPreview>

## Header [#header]

Wrap the top row in `CodeBlockHeader`. Use `CodeBlockTitle` for the filename and `CodeBlockActions` for buttons.

<ComponentPreview name="code-block-header" title="code-block-header.tsx" src="examples/code-block-header.tsx">
<CodeBlockHeaderDemo />
</ComponentPreview>

## Actions [#actions]

`CodeBlockActions` can hold multiple buttons — copy, download, wrap toggle. Each is a plain `Button`.

<ComponentPreview name="code-block-actions" title="code-block-actions.tsx" src="examples/code-block-actions.tsx">
<CodeBlockActionsDemo />
</ComponentPreview>

## Floating Actions [#floating-actions]

Place `CodeBlockActions` **directly inside** `CodeBlock` (no header) — the buttons float top-end and fade in on hover.

<ComponentPreview name="code-block-floating-actions" title="code-block-floating-actions.tsx" src="examples/code-block-floating-actions.tsx">
<CodeBlockFloatingActionsDemo />
</ComponentPreview>

## Line Numbers [#line-numbers]

Add `lineNumbers` to `CodeBlockContent`. Line numbers **are not copied** when the user selects the code.

<ComponentPreview name="code-block-line-numbers" title="code-block-line-numbers.tsx" src="examples/code-block-line-numbers.tsx">
<CodeBlockLineNumbersDemo />
</ComponentPreview>

## Start Line [#start-line]

Set `startLine` to begin numbering from a different number — useful when showing a snippet from the middle of a file.

<ComponentPreview name="code-block-start-line" title="code-block-start-line.tsx" src="examples/code-block-start-line.tsx">
<CodeBlockStartLineDemo />
</ComponentPreview>

## Wrap [#wrap]

Add `wrap` to `CodeBlockContent` to break long lines instead of scroll. Compare both sides:

<ComponentPreview name="code-block-wrap" title="code-block-wrap.tsx" src="examples/code-block-wrap.tsx">
<CodeBlockWrapDemo />
</ComponentPreview>

## Highlighted Lines [#highlighted-lines]

Use `CodeBlockLine` with `variant="highlighted"` to draw attention to specific lines.

<ComponentPreview name="code-block-highlighted-lines" title="code-block-highlighted-lines.tsx" src="examples/code-block-highlighted-lines.tsx">
<CodeBlockHighlightedLinesDemo />
</ComponentPreview>

## Diff [#diff]

Use `variant="added"` and `variant="removed"`. The `+` and `−` markers are added by CSS — no need to type them.

<ComponentPreview name="code-block-diff" title="code-block-diff.tsx" src="examples/code-block-diff.tsx">
<CodeBlockDiffDemo />
</ComponentPreview>

## Height [#height]

Constrain height with a `max-h-*` class on `CodeBlockContent`. Content becomes scrollable — good for long build logs.

<ComponentPreview name="code-block-height" title="code-block-height.tsx" src="examples/code-block-height.tsx" previewClassName="h-auto">
<CodeBlockHeightDemo />
</ComponentPreview>

## Size [#size]

Two sizes: `default` (14px, 16px padding) and `sm` (12px, 12px padding). `sm` fits inside compact slots.

<ComponentPreview name="code-block-size" title="code-block-size.tsx" src="examples/code-block-size.tsx">
<CodeBlockSizeDemo />
</ComponentPreview>

## Destructive [#destructive]

Use `variant="destructive"` for error output. Background and text shift to destructive tone.

<ComponentPreview name="code-block-destructive" title="code-block-destructive.tsx" src="examples/code-block-destructive.tsx">
<CodeBlockDestructiveDemo />
</ComponentPreview>

## In Context [#in-context]

### Documentation snippet [#documentation-snippet]

<ComponentPreview name="code-block-documentation" title="code-block-documentation.tsx" src="examples/code-block-documentation.tsx">
<CodeBlockDocumentationDemo />
</ComponentPreview>

## API Reference [#api-reference]

### CodeBlock [#codeblock]

<PropsTable rows={[{"name":"variant","type":"default | destructive","default":"default","description":"Visual style of the container."},{"name":"size","type":"default | sm","default":"default","description":"Text size and padding scale."}]} />

### CodeBlockContent [#codeblockcontent]

<PropsTable rows={[{"name":"wrap","type":"boolean","default":"false","description":"Wrap long lines instead of horizontal scroll."},{"name":"lineNumbers","type":"boolean","default":"false","description":"Render line numbers. Requires string children."},{"name":"startLine","type":"number","default":"1","description":"First line number when lineNumbers is enabled."}]} />

### CodeBlockLine [#codeblockline]

<PropsTable rows={[{"name":"variant","type":"default | added | removed | highlighted","default":"default","description":"Visual diff or highlight style for the line."}]} />

## Accessibility [#accessibility]

- **CodeBlockContent** has `tabIndex={0}` for keyboard scroll.
- **CodeBlockCopyButton** has `aria-label` and a `aria-live` region announcing "Copied".
- Use **CodeBlockTitle** as the accessible name of the block.

## Composition [#composition]

```text
CodeBlock
├── CodeBlockHeader
│   ├── CodeBlockTitle
│   └── CodeBlockActions
├── CodeBlockContent
├── CodeBlockCopyButton
└── CodeBlockFooter
```

## Best Practices [#best-practices]

- **Set a max-height.** Long files push the layout.
- **Show the file name.** Users need to know where the code goes.
- **Copy action on hover, not always.** Reduces visual noise.
- **Do not highlight unknown languages.** Fall back to plain text.