Code blocks and groups

Display inline code and code blocks with syntax highlighting, line highlighting, focus effects, and tabbed interfaces for multiple examples.

Overview

Use code blocks to show syntax-highlighted code with a built-in copy button. Use code groups when you want tabs (for example, "JavaScript," "Python," and "cURL") so readers can switch between multiple examples in one place.

Code blocks and groups are ideal for:

• Single code snippets with syntax highlighting and copy support
• Multi-language SDK examples in tabs (similar to Tabs)
• Before/after, request/response, or setup/usage comparisons
• Step-by-step walkthroughs when combined with Steps

At a high level:

• Code blocks: One snippet, one language.
• Code groups: Multiple snippets, each with its own language and tab.

You can create both from the Web Editor or by writing MDX/Markdown in the Code Editor. The underlying syntax is the same, so you can safely switch between editors.

Using with Web Editor

In the Web Editor, use the slash menu to insert and manage code blocks and groups.

Insert a code block

1. Place your cursor on a new line.
2. Type / and select Code Block.
3. A code block appears with the placeholder "Add your code here…". Paste or type your code into the block.

Use the language dropdown on the top-right of the block to pick the correct language. This controls syntax highlighting and the copy behavior.

Insert a code group

1. Place your cursor on a new line.
2. Type / and select Code Group.
3. A group is created with a default tab (for example, Tab 1) and a code editor area.

Inside a code group you can:

• Add a tab: Click the + next to the last tab.
• Rename a tab: Double-click the tab label (for example, "Tab 1") and type a new name (for example, "TypeScript" or "Python").
• Remove a tab: Use the tab's close icon (if available) or delete the last remaining tab to remove the group.
• Pick a language per tab: Use the language dropdown on each tab's code block.

The group toolbar also lets you duplicate or delete the entire group.

Prefer writing in code?

You can switch to MDX view inside the Web Editor to write or edit this component using the same syntax as the Code Editor. This is useful if you want full control while staying in the Web Editor.

Using with Code Editor

When working in a code editor, you write code blocks and code groups with standard fenced code syntax and the <CodeGroup> component.

Single code block

Use fenced code blocks with three backticks and a language identifier:

const apiCall = async () => {
  const response = await fetch("/api/docs");
  return response.json();
};

```typescript
const apiCall = async () => {
const response = await fetch("/api/docs");
return response.json();
};
```

CodeGroup with multiple languages

Wrap multiple fenced code blocks in a <CodeGroup> component to render them as tabs:

<CodeGroup tabs="TypeScript,Python,Bash">
```typescript
const response = await fetch("/api/docs", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ title: "Getting Started" })
});
```

```python
import requests

response = requests.post(
"https://api.example.com/docs",
json={"title": "Getting Started"}
)
```

```bash
curl -X POST https://api.example.com/docs \
  -H "Content-Type: application/json" \
  -d '{"title": "Getting Started"}'
```
</CodeGroup>

Notes:

• Each fenced block inside <CodeGroup> must have a language tag (for example, typescript, python, bash).
• tabs="TypeScript,Python,Bash" controls the visible tab labels. If you omit tabs, the language names are used instead.
• You can combine <CodeGroup> with Tabs or Steps when you need more complex layouts.

Advanced options

Use these attributes and patterns to fine-tune how code blocks and groups render.

Line highlighting

Use the highlight prop on a fenced code block to emphasize specific lines:

const greeting = "Hello, World!";
function sayHello() {
  console.log(greeting);
}
sayHello();

```javascript highlight="1-2,5"
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```

Line focus

Use the focus prop to dim non-focused lines and draw attention to a subset of the code:

const greeting = "Hello, World!";
function sayHello() {
  console.log(greeting);
}
sayHello();

```javascript focus="2,4-5"
const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}
sayHello();
```

Line numbers

Combine highlighting or focus with line numbers using show-lines={true}:

interface User {
  name: string;
  age: number;
}

```typescript highlight="1,3" show-lines="true"
interface User {
name: string;
age: number;
}
```

Wrap long lines

Use the wrap parameter to control whether long lines stay on a single row with horizontal scrolling or automatically wrap onto the next visual line inside the code block.

You can enable wrapping in several equivalent ways on a fenced block: wrap, wrap="true", wrap=true.

const longLine = "This is a very long line of code that would normally require horizontal scrolling, but with wrap enabled it will wrap to the width of the container instead of overflowing.";

You can also combine wrap with other parameters like highlight and show-lines:

```typescript highlight="1" show-lines="true" wrap="true"
const longLine = "This line is highlighted, shows a line number, and wraps instead of scrolling horizontally across the viewport.";
```

When to use wrapping:

• Use wrap when you want readers to see the full line without side-scrolling (for example, configuration files or long shell commands), especially in narrow layouts or on mobile devices.
• Avoid wrap when alignment and spacing matter (for example, formatted logs, tables, or columns rendered in code), where wrapping can make structure harder to see.

CodeGroup options

<CodeGroup> supports the same block-level props (for example, highlight, focus, show-lines) inside each tabbed code block.

<CodeGroup tabs="TypeScript,Python,Bash">
```typescript
const response = await fetch('/api/docs', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ title: 'Getting Started' })
});
```

```python
import requests
response = requests.post('/api/docs',
json={'title': 'Getting Started'}
)
```

```bash
curl -X POST https://api.example.com/docs \
  -H "Content-Type: application/json" \
  -d '{"title": "Getting Started"}'
```
</CodeGroup>

You can also control tabs explicitly:

• tabs: Comma-separated list of tab labels, for example tabs="TypeScript,Python,Bash".
• show-lines: Set on the component (for example, show-lines={true}) to show line numbers for all blocks in the group.

``` ````

const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}

const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}

If you omit tabs, language identifiers are used as labels:

``` ````

const example = "This tab shows: typescript";

example = "This tab shows: python";

Auto-detected tabs

Without the tabs attribute, CodeGroup automatically uses language identifiers as tab names:

``` ````

const example = "This tab shows: typescript";

example = "This tab shows: python"

CodeGroup with highlighting and focus

Line highlighting and focus effects work within CodeGroup tabs:

const greeting = "Hello, World!";
function sayHello() {
  console.log(greeting);
}

``` ````

const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}

const greeting = "Hello, World!";
function sayHello() {
console.log(greeting);
}

Nested code examples (four backticks)

When you need to show code that itself contains code fences, wrap the outer block in four backticks:

"""typescript
```typescript
function calculateTotal(price: number, tax: number): number {
  return price + (price * tax);
}
```
"""

Attribute reference

Use these attributes on fenced code blocks or <CodeGroup>:

path\highlightstring

Line numbers or ranges to highlight. Examples: "1", "1-3", "1,3,5-7".

path\focusstring

Line numbers or ranges to focus on (blurs other lines). Examples: "2", "2-4", "1,4-6".

path\show-linesboolean \| string

Set to {true} to show line numbers for a block or an entire group.

path\tabsstring

Comma-separated custom tab names (for example, "TypeScript,Python,Bash"). Overrides auto-detected language labels.

path\wrapboolean \| string

Controls whether long lines wrap inside the code block. Defaults to false (no wrapping, horizontal scrolling). Set using wrap, wrap="true", or wrap={true} to enable white-space: pre-wrap and word-break: break-word with vertical scrolling only.