Code Block

Code blocks render and apply syntax highlighting to blocks of code. The mantleCodeBlockPlugins() Vite plugin highlights the code at build time with Shiki, so there is zero highlighting cost in the browser.

Use mantleCode("language") tagged template literals to define code values. The Vite plugin transforms these at build time, inlining pre-rendered HTML.

1const listener = await ngrok.connect({⋯2	// session configuration3	addr: `localhost:8080`, // or `8080` or `unix:${UNIX_SOCKET}`4	authtoken: "<authtoken>",5	authtoken_from_env: true,6	on_status_change: (addr, error) => {⋯7		console.log(`disconnected, addr ${addr} error: ${error}`);8	},9	session_metadata: "Online in One Line",10	// listener configuration11	allow_user_agent: "^mozilla.*",12	basic_auth: ["ngrok:online1line"],13	circuit_breaker: 0.1,14	compression: true,15	deny_user_agent: "^curl.*",16	domain: "<domain>",17	ip_restriction_allow_cidrs: ["0.0.0.0/0"],18	ip_restriction_deny_cidrs: ["10.1.1.1/32"],19	metadata: "example listener metadata from nodejs",20	mutual_tls_cas: [fs.readFileSync('ca.crt', 'utf8')],21	oauth_provider: "google",22	oauth_allow_domains: ["<domain>"],23	oauth_allow_emails: ["<email>"],24	oauth_scopes: ["<scope>"],25	oauth_client_id: "<id>",26	oauth_client_secret: "<secret>",27	oidc_issuer_url: "<url>",28	oidc_client_id: "<id>",29	oidc_client_secret: "<secret>",30	oidc_allow_domains: ["<domain>"],31	oidc_allow_emails: ["<email>"],32	oidc_scopes: ["<scope>"],33	proxy_proto: "", // One of: "", "1", "2"34	request_header_remove: ["X-Req-Nope"],35	response_header_remove: ["X-Res-Nope"],36	request_header_add: ["X-Req-Yup:true"],37	response_header_add: ["X-Res-Yup:true"],38	schemes: ["HTTPS"],39	verify_webhook_provider: "twilio",40	verify_webhook_secret: "asdf",41	websocket_tcp_converter: true,42});

1import { CodeBlock, mantleCode } from "@ngrok/mantle/code-block";2 3<CodeBlock.Root>⋯4	<CodeBlock.Header>⋯5		<CodeBlock.Icon preset="file" />6		<CodeBlock.Title>…</CodeBlock.Title>7	</CodeBlock.Header>8	<CodeBlock.Body>⋯9		<CodeBlock.CopyButton />10		<CodeBlock.Code value={mantleCode("javascript")`…`} />11	</CodeBlock.Body>12	<CodeBlock.ExpanderButton />13</CodeBlock.Root>;

Examples

Single line with a header

Many code blocks will be single line command line prompts and should be able to render with a header and copy button. This makes it absolutely clear that this example is a command line prompt and not a code sample.

sudo unzip ~/Downloads/ngrok-v3-stable-darwin.zip -d /usr/local/bin

1<CodeBlock.Root>⋯2	<CodeBlock.Header>⋯3		<CodeBlock.Icon preset="cli" />4		<CodeBlock.Title>Command Line</CodeBlock.Title>5	</CodeBlock.Header>6	<CodeBlock.Body>⋯7		<CodeBlock.CopyButton />8		<CodeBlock.Code⋯9			value={mantleCode(10				"bash",11			)`sudo unzip ~/Downloads/ngrok-v3-stable-darwin.zip -d /usr/local/bin`}12		/>13	</CodeBlock.Body>14</CodeBlock.Root>

Horizontal scrolling

This example is included to demonstrate that code blocks can scroll horizontally if the content is too wide. Mantle attempts to normalize scrollbar styling across browsers and platforms.

When line numbers are shown, the gutter (numbers and fold toggles) stays pinned to the left edge while the code scrolls under it.

1const http = require('http');2const ngrok = require("@ngrok/ngrok");3const server = http.createServer((req, res) => {⋯4	res.writeHead(200);5	res.end("Hello!");6	setTimeout(() => {⋯7		Promise.resolve().then(() => {⋯8			console.log("url:", server.tunnel.url());9		});10	}, timeout);11});12// Consumes authtoken from env automatically13ngrok.listen(server).then(() => {⋯14	console.log("url:", server.tunnel.url());15});16// really long line here that should wrap around and stuff Officia ipsum sint eu labore esse deserunt aliqua quis irure.

1<CodeBlock.Root>⋯2	<CodeBlock.Header>⋯3		<CodeBlock.Icon preset="file" />4		<CodeBlock.Title>ngrok-example.js</CodeBlock.Title>5	</CodeBlock.Header>6	<CodeBlock.Body>⋯7		<CodeBlock.CopyButton />8		<CodeBlock.Code⋯9			value={mantleCode("javascript")`⋯10				const http = require('http');11				const ngrok = require("@ngrok/ngrok");12				const server = http.createServer((req, res) => {13					res.writeHead(200);14					res.end("Hello!");15					setTimeout(() => {16						Promise.resolve().then(() => {17							console.log("url:", server.tunnel.url());18						});19					}, timeout);20				});21				// Consumes authtoken from env automatically22				ngrok.listen(server).then(() => {23					console.log("url:", server.tunnel.url());24				});25				// really long line here that should wrap around and stuff Officia ipsum sint eu labore esse deserunt aliqua quis irure.26			`}27		/>28	</CodeBlock.Body>29</CodeBlock.Root>

No header or copy button

This is the most simple example of our code block component. While very useful, the copy button is optional. It is also perfectly acceptable to render a code block without a header, especially if the surrounding content carries the context or the code block is self-explanatory eg. "In your index.js file, paste the following:".

1const http = require('http');2const ngrok = require("@ngrok/ngrok");3const server = http.createServer((req, res) => {⋯4	res.writeHead(200);5	res.end("Hello!");6});7// Consumes authtoken from env automatically8ngrok.listen(server).then(() => {⋯9	console.log("url:", server.tunnel.url());10});

1<CodeBlock.Root>⋯2	<CodeBlock.Body>⋯3		<CodeBlock.Code⋯4			value={mantleCode("javascript")`⋯5				const http = require('http');6				const ngrok = require("@ngrok/ngrok");7				const server = http.createServer((req, res) => {8					res.writeHead(200);9					res.end("Hello!");10				});11				ngrok.listen(server).then(() => {12					console.log("url:", server.tunnel.url());13				});14			`}15		/>16	</CodeBlock.Body>17</CodeBlock.Root>

Single line with horizontal scrolling

This example is included to show the interaction between the copy button and horizontal scrolling on a single verbose terminal command.

ffmpeg -i multichannel.mxf -map 0:v:0 -map 0:a:0 -map 0:a:0 -c:a:0 ac3 -b:a:0 640k -ac:a:1 2 -c:a:1 aac -b:2 128k out.mp4

1<CodeBlock.Root>⋯2	<CodeBlock.Body>⋯3		<CodeBlock.CopyButton />4		<CodeBlock.Code⋯5			value={mantleCode(6				"bash",7			)`ffmpeg -i multichannel.mxf -map 0:v:0 -map 0:a:0 -map 0:a:0 -c:a:0 ac3 -b:a:0 640k -ac:a:1 2 -c:a:1 aac -b:2 128k out.mp4`}8		/>9	</CodeBlock.Body>10</CodeBlock.Root>

Server-rendered syntax highlighting

The CodeBlock supports server-rendered syntax highlighting for dynamic or user-supplied code. Use createMantleCodeBlockValue() to construct a value from server-highlighted HTML and pass it to CodeBlock.Code. This is useful when the code to highlight isn't known at build time (for example, user input or API responses).

1import {2	CodeBlock,3	createMantleCodeBlockValue,4	type MantleCodeBlockValue,5} from "@ngrok/mantle/code-block";6 7// Fetch highlighted HTML from your server8const response = await fetch("/api/shiki-highlight", {⋯9	method: "POST",10	headers: { "Content-Type": "application/json" },11	body: JSON.stringify({ code, language: "typescript", showLineNumbers: true }),12});13const data = await response.json();14 15// Create a MantleCodeBlockValue from the server response16const value: MantleCodeBlockValue = createMantleCodeBlockValue({⋯17	code: data.code,18	language: "typescript",19	preHtml: data.html,20	showLineNumbers: data.showLineNumbers,21	highlightLines: data.highlightLines,22	lineNumberStart: data.lineNumberStart,23});24 25<CodeBlock.Root>⋯26	<CodeBlock.Body>⋯27		<CodeBlock.CopyButton />28		<CodeBlock.Code value={value} />29	</CodeBlock.Body>30</CodeBlock.Root>;

Highlight microservice (for Go / non-Node.js backends)

For frontends backed by non-Node.js services (Go, Python, etc.), deploy a small Node.js highlight service as a sidecar or shared microservice. This gives you the same server-rendered highlighting without shipping Shiki to the browser; the frontend calls the API with fetch.

Create a highlight server using createMantleServerSyntaxHighlighter:

1// highlight-service.ts — deploy as a sidecar alongside your Go service2import { createServer } from "node:http";3import { createMantleServerSyntaxHighlighter } from "@ngrok/mantle-server-syntax-highlighter";4 5const highlighter = createMantleServerSyntaxHighlighter();6 7createServer(async (req, res) => {⋯8	// Handle CORS9	res.setHeader("Access-Control-Allow-Origin", "*");10	res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");11	res.setHeader("Access-Control-Allow-Headers", "Content-Type");12	if (req.method === "OPTIONS") {⋯13		res.writeHead(204).end();14		return;15	}16 17	const chunks: Buffer[] = [];18	for await (const chunk of req) chunks.push(chunk);19	const { code, language, showLineNumbers, highlightLines, lineNumberStart } = JSON.parse(20		Buffer.concat(chunks).toString(),21	);22 23	const result = await highlighter.highlight({⋯24		code,25		language,26		showLineNumbers,27		highlightLines,28		lineNumberStart,29	});30	res.writeHead(200, { "Content-Type": "application/json" }).end(JSON.stringify(result));31}).listen(4444, () => console.log("Highlight server on :4444"));

Then use it from any frontend the same way as the server-rendered example above, pointing at the highlight service URL:

1const response = await fetch("http://localhost:4444", {⋯2	method: "POST",3	headers: { "Content-Type": "application/json" },4	body: JSON.stringify({ code, language: "json", showLineNumbers: true }),5});6const data = await response.json();7 8const value = createMantleCodeBlockValue({⋯9	code: data.code,10	language: data.language,11	preHtml: data.html,12	showLineNumbers: data.showLineNumbers,13});

Foldable code blocks

Code blocks automatically render editor-style fold carets in the gutter for any block whose language has a folding strategy: AST-based (JS/TS/JSX/TSX, HTML, XML), raw-source (JSON, CSS), bracket-paired (Go, Java, C#, Rust, Terraform), indentation-based (Python, YAML), keyword-paired (Bash/Shell), or bracket + keyword (Ruby). Click the caret (or focus and press Enter / Space) to collapse the inner lines; the opener and closer lines stay visible, and a ⋯ placeholder marks the collapsed region.

Folding is computed before the block reaches the browser, and the entire interaction runs through a single delegated click handler per code block: no per-line listeners and no React re-renders on toggle. This keeps fold/unfold cheap even for code blobs with thousands of lines.

The mantleCode() Vite transform, MDX code fences, and createMantleServerSyntaxHighlighter() use the full server-side folding dispatcher. The lower-level computeFoldRanges({ language, tokens }) export from @ngrok/mantle/highlight-utils is intentionally token-only for custom integrations; it covers bracket, indentation, and tag folds only. Use @ngrok/mantle-server-syntax-highlighter for AST, raw-source, or keyword strategies.

For one example per supported language plus a list of caveats, see folding by language.

1{⋯2  "name": "@ngrok/mantle",3  "version": "0.71.0",4  "scripts": {⋯5    "build": "tsdown",6    "test": "vitest run",7    "typecheck": "tsc"8  },9  "dependencies": {⋯10    "@radix-ui/react-tabs": "1.1.13",11    "clsx": "2.1.1",12    "tailwind-merge": "3.5.0"13  },14  "pnpm": {⋯15    "onlyBuiltDependencies": [⋯16      "esbuild",17      "@tailwindcss/oxide"18    ]19  }20}

1import { CodeBlock, mantleCode } from "@ngrok/mantle/code-block";2 3<CodeBlock.Root>⋯4	<CodeBlock.Header>⋯5		<CodeBlock.Icon preset="file" />6		<CodeBlock.Title>package.json</CodeBlock.Title>7	</CodeBlock.Header>8	<CodeBlock.Body>⋯9		<CodeBlock.CopyButton />10		<CodeBlock.Code⋯11			value={mantleCode("json")`⋯12				{13					"name": "@ngrok/mantle",14					"scripts": {15						"build": "tsdown",16						"test": "vitest run"17					},18					"pnpm": {19						"onlyBuiltDependencies": [20							"esbuild",21							"@tailwindcss/oxide"22						]23					}24				}25			`}26		/>27	</CodeBlock.Body>28</CodeBlock.Root>;

Highlighting runtime JSON on the client

mantleCode() highlights at build time, so it can't highlight a value you only have at runtime: an API response, a table row's underlying record, anything fetched or computed in the browser. For that, use jsonCodeBlockValue(value): it serializes the value with JSON.stringify (2-space indent), tokenizes it, and returns a MantleCodeBlockValue you pass straight to CodeBlock.Code, entirely on the client, with no Shiki runtime, grammar, or WASM shipped to the browser (~1 KB). Because Mantle highlights with a CSS-variables theme the colors already live in CSS, so only tokenization happens at runtime; the output is byte-for-byte identical to a server/build-time highlighted block and adapts to light/dark themes for free.

Multi-line objects and arrays are collapsible by default (the same fold runtime as every other JSON block), so pass { foldable: false } for a flat panel, or { showLineNumbers: true } for a gutter. Serialization is safe and never throws: BigInt renders as its decimal string, circular/repeated references collapse to "[Circular]", and values that serialize to undefined render as an empty string. It's ideal for inspecting a record inside a DataTable.ExpandedRow.

{⋯  "id": "evt_31kPq9aZ",  "type": "endpoint.created",  "created_at": "2025-06-18T17:42:10Z",  "endpoint": {⋯    "id": "ep_2hYqLm4",    "region": "us-east-1",    "url": "https://example.ngrok.app",    "bindings": [⋯      "public",      "internal"    ]  },  "metadata": {⋯    "source": "api",    "retries": 0,    "ok": true  }}

1import { CodeBlock, jsonCodeBlockValue } from "@ngrok/mantle/code-block";2 3// `record` is any runtime value — an API response, a table row's object, etc.4<CodeBlock.Root>⋯5	<CodeBlock.Body>⋯6		<CodeBlock.CopyButton />7		<CodeBlock.Code value={jsonCodeBlockValue(record)} />8	</CodeBlock.Body>9</CodeBlock.Root>;10 11// Opt out of folding, or show a line-number gutter:12jsonCodeBlockValue(record, { foldable: false });13jsonCodeBlockValue(record, { showLineNumbers: true });

For lower-level control, jsonToShikiHtml(code) returns only the Shiki-identical inner HTML for a <code> element (no line-number or fold decoration); jsonCodeBlockValue builds on it.

Tabbed code block

Use CodeBlock.TabList, CodeBlock.TabTrigger, and CodeBlock.TabContent to create a tabbed code block. Pass defaultTab (or activeTab / onActiveTabChange for controlled mode) to CodeBlock.Root, place the tab triggers in the CodeBlock.Header, and wrap each CodeBlock.Code in a CodeBlock.TabContent. The copy button automatically copies whichever code is currently displayed.

1on_http_request:⋯2  - expressions:⋯3      # conditions are CEL expressions, see https://cel.dev4      - req.url.path.startsWith('/api')5    actions:⋯6      - type: forward-internal⋯7        config:⋯8          url: https://api.internal9 10  # route dynamically based on a header using CEL interpolation11  - actions:⋯12      - type: forward-internal⋯13        config:⋯14          url: "https://${req.headers('X-Custom-Header')}.internal"

1import { CodeBlock, mantleCode } from "@ngrok/mantle/code-block";2 3const policyYml = mantleCode("yaml")`…`;4const policyJson = mantleCode("json")`…`;5 6<CodeBlock.Root defaultTab="yml">⋯7	<CodeBlock.Header>⋯8		<CodeBlock.TabList>⋯9			<CodeBlock.TabTrigger value="yml">policy.yml</CodeBlock.TabTrigger>10			<CodeBlock.TabTrigger value="json">policy.json</CodeBlock.TabTrigger>11		</CodeBlock.TabList>12	</CodeBlock.Header>13	<CodeBlock.Body>⋯14		<CodeBlock.CopyButton />15		<CodeBlock.TabContent value="yml">⋯16			<CodeBlock.Code value={policyYml} />17		</CodeBlock.TabContent>18		<CodeBlock.TabContent value="json">⋯19			<CodeBlock.Code value={policyJson} />20		</CodeBlock.TabContent>21	</CodeBlock.Body>22</CodeBlock.Root>;

When the tabs are too wide for the header, CodeBlock.TabList scrolls horizontally with a scroll-fade-x edge fade instead of wrapping onto a second row (no extra wiring required).

1console.log("Hello, ngrok!");

Reusing fragments with nested interpolation

A mantleCode value can be embedded into another mantleCode template by interpolating its .code property. When the Vite plugin recognizes the reference, it inlines the fragment's source at build time, so the embedded code is highlighted line-for-line in its host language (correct line numbers, folding, and copy text) with no runtime substitution cost.

This is ideal for sharing a Traffic Policy or config snippet across multiple SDK examples without duplicating it. The fragment can live at the top level of the same module, or be imported from another module:

1var policy = """2on_http_request:3	- actions:4			- type: oauth5				config:6					provider: google7""";8 9var agent = Session.withAuthtoken(authtoken).connect();10var listener = agent.listen(policy);

1// shared-policies.ts — author the reusable policy once.2import { mantleCode } from "@ngrok/mantle/code-block";3 4export const oauthPolicyFragment = mantleCode("yaml")`on_http_request:⋯5	- actions:6			- type: oauth7				config:8					provider: google`;

1// listener-demo.tsx — embed it into a Java text block.2import { CodeBlock, mantleCode } from "@ngrok/mantle/code-block";3import { oauthPolicyFragment } from "./shared-policies";4 5// `${oauthPolicyFragment.code}` is resolved and inlined at build time.6const javaSdkSnippet = mantleCode("java")`var policy = """⋯7${oauthPolicyFragment.code}8""";9 10var listener = agent.listen(policy);`;

The fragment must be a top-level mantleCode const referenced as .code: either declared earlier in the same module, or a named import of a directly-exported top-level const from another module. Nested fragments are resolved recursively. Interpolations that can't be resolved statically (dynamic values, re-exports, bare identifiers without .code) fall back to runtime placeholder substitution, and an unresolved imported .code reference emits a build warning. The embedded source is highlighted with the outer language's grammar (e.g. the YAML above is highlighted as Java text-block content, not as YAML).

mantleCode() options

The mantleCode() tagged template accepts an optional second argument with the following options:

• showLineNumbers: Whether to show line numbers. Defaults to true for most languages, but false for single-line shell snippets (bash, sh, shell). Pass false to hide them or true to force them on.
• highlightLines: An array of line numbers or ranges (e.g. [2, "4-5"]) to visually highlight.
• lineNumberStart: The starting line number when line numbers are displayed. Defaults to 1.
• indentation: Override the default indentation style ("tabs" or "spaces").

import { serve } from "bun"; const server = serve({⋯  port: 3000,  fetch(req) {⋯    return new Response("Hello from Bun!");  },}); console.log(`Listening on ${server.url}`);

1import { CodeBlock, mantleCode } from "@ngrok/mantle/code-block";2 3<CodeBlock.Root>⋯4	<CodeBlock.Header>⋯5		<CodeBlock.Icon preset="file" />6		<CodeBlock.Title>all-options.ts</CodeBlock.Title>7	</CodeBlock.Header>8	<CodeBlock.Body>⋯9		<CodeBlock.CopyButton />10		<CodeBlock.Code⋯11			value={mantleCode("typescript", {⋯12				showLineNumbers: false,13				highlightLines: [11, "13-14"],14				lineNumberStart: 10,15				indentation: "spaces",16			})`⋯17				import { serve } from "bun";18 19				const server = serve({20					port: 3000,21					fetch(req) {22						return new Response("Hello from Bun!");23					},24				});25 26				console.log(\`Listening on \${server.url}\`);27			`}28		/>29	</CodeBlock.Body>30</CodeBlock.Root>;

Overriding defaults

The mantleCode() options let you customize how code is displayed. By default, line numbers are shown starting at 1 and indentation is inferred from the language. You can also specify highlighted lines per code block. The first example below uses the defaults (YAML auto-detects space indentation), while the second overrides all options: custom indentation, line number start, highlighted lines, and visible line numbers.

1# yaml indentation MUST use spaces (we infer this for you)2on_http_request:⋯3  actions:⋯4    type: custom-response5    config:⋯6      status_code: 2007      content: Hello, World!

42// by default, mantle decides that javascript uses tabs,43// but this example uses spaces for indentation44const http = require('http');45const ngrok = require("@ngrok/ngrok");46const server = http.createServer((req, res) => {⋯47  res.writeHead(200);48  res.end("Hello!");49  setTimeout(() => {⋯50    Promise.resolve().then(() => {⋯51      console.log("url:", server.tunnel.url());52    });53  }, timeout);54});55// Consumes authtoken from env automatically56ngrok.listen(server).then(() => {⋯57  console.log("url:", server.tunnel.url());58});

1{⋯2	/* yaml auto-detects space indentation, all other defaults apply */3}4<CodeBlock.Code⋯5	value={mantleCode("yaml")`⋯6		on_http_request:7			actions:8				type: custom-response9				config:10					status_code: 20011					content: Hello, World!12	`}13/>;14 15{⋯16	/* override all mantleCode() options */17}18<CodeBlock.Code⋯19	value={mantleCode("javascript", {⋯20		indentation: "spaces",21		showLineNumbers: true,22		highlightLines: [42, "46-48"],23		lineNumberStart: 42,24	})`⋯25		const http = require('http');26		const ngrok = require("@ngrok/ngrok");27		const server = http.createServer((req, res) => {28			res.writeHead(200);29			res.end("Hello!");30		});31	`}32/>;

Composition

Compose the parts of a CodeBlock together to build your own:

# StandardCodeBlock.Root├── CodeBlock.Header│   ├── CodeBlock.Icon│   └── CodeBlock.Title├── CodeBlock.Body│   ├── CodeBlock.CopyButton│   └── CodeBlock.Code└── CodeBlock.ExpanderButton# TabbedCodeBlock.Root├── CodeBlock.Header│   └── CodeBlock.TabList│       └── CodeBlock.TabTrigger├── CodeBlock.Body│   ├── CodeBlock.CopyButton│   └── CodeBlock.TabContent│       └── CodeBlock.Code└── CodeBlock.ExpanderButton

Polymorphism

CodeBlock.Root, CodeBlock.Header, CodeBlock.Title, CodeBlock.Body, and CodeBlock.CopyButton accept asChild. When true the part renders its single child instead of its default element, forwarding class names, data-* attributes, and ref onto it.

Reach for it when Root should be a semantic <figure> or <section>, when Title needs a different heading level than the default <h3>, or when Header and Body should be <header> and <section>. CopyButton has no children of its own, so it is typed SelfClosingWithAsChild: <CodeBlock.CopyButton asChild> requires exactly one child to clone, and forbids children otherwise.

The remaining parts do not accept asChild. CodeBlock.Code owns the highlighted markup it renders, and CodeBlock.TabList, CodeBlock.TabTrigger, and CodeBlock.TabContent each explicitly omit the prop because their behavior and mounting are driven by the active tab. CodeBlock.Icon takes its element through the svg prop instead. CodeBlock.ExpanderButton renders its own "Show more" / "Show less" label and caret icon, so there is no single child to clone; style it with className.

Translation

CodeBlock.Code and CodeBlock.Title carry translate="no", so a browser translation engine skips the code and the filename. A translated CLI flag, env var, or YAML key is wrong, and the reader copies it anyway. A translated example.ts names a file that does not exist.

The attribute also protects the render itself: Google Translate replaces each text node with a <font> wrapper, which detaches the text nodes React holds, so React either writes updates into a node the DOM no longer shows, or throws NotFoundError from removeChild and tears down the root.

The two parts differ on whether a call site may turn the guard off. CodeBlock.Code omits the translate prop from its type, because a block of code is never translatable. CodeBlock.Title keeps it, because the slot takes arbitrary children; pass translate="yes" for a title that is prose rather than a filename.

Accessibility

• CodeBlock.CopyButton is an icon button named by label (default "Copy code"). After a copy, an always-mounted role="status" element beside the button announces "Copied", so a screen-reader user hears the result and not only the icon swap.
• CodeBlock.ExpanderButton carries aria-expanded and aria-controls that points at the <pre>. The <pre> itself carries no ARIA state; data-state="collapsed" | "expanded" drives the styling.
• Fold toggles are real <button> elements named "Toggle code folding" with aria-expanded. Enter and Space toggle them. The folded marker is aria-hidden.
• Line numbers are aria-hidden, so a screen reader reads the code, not "1 const x".
• CodeBlock.Code and CodeBlock.Title carry translate="no"; see Translation.

API Reference

The CodeBlock renders and applies syntax highlighting to blocks of code and is composed of several sub-components.

CodeBlock.Root

Root container for all CodeBlock sub-components. For tabbed code blocks, pass defaultTab (uncontrolled) or activeTab / onActiveTabChange (controlled) to enable tab switching.

All props from standard HTML div attributes, plus:

CodeBlock.Body

The body of the CodeBlock. This is where the CodeBlock.Code and optional CodeBlock.CopyButton are rendered as direct children.

All props from standard HTML div attributes, plus:

CodeBlock.Code

The CodeBlock content. This is where the code is rendered with pre-highlighted Shiki HTML.

The <pre> always carries translate="no".

All props from standard HTML pre attributes except translate, plus:

Inside the highlighted HTML, data-slot="line-number", data-slot="fold-toggle", and data-slot="fold-ellipsis" mark the gutter number, the fold button, and the folded marker.

CodeBlock.Header

An optional header slot of the CodeBlock. This is where things like the CodeBlock.Icon and CodeBlock.Title are rendered.

All props from standard HTML div attributes, plus:

CodeBlock.Title

The (optional) title of a CodeBlock. Default renders as an h3 element; use asChild to render something else.

The heading carries translate="no" by default, because the title usually names a file.

All props from standard HTML h3 attributes, plus:

CodeBlock.CopyButton

The optional copy button. Render it as a child of CodeBlock.Body. It copies the raw source of the mounted CodeBlock.Code to the clipboard — in a tabbed block, the active tab's code.

All props from standard HTML button attributes, plus:

After a copy, an always-mounted role="status" element inside the part announces "Copied".

CodeBlock.ExpanderButton

The (optional) expander button of the CodeBlock. Render this as a child of the CodeBlock.Root to allow users to expand/collapse the code block contents. It carries aria-expanded and aria-controls that points at the <pre>. It does not take asChild: it renders its own label and caret, so style it with className.

All props from standard HTML button attributes except children, aria-controls, and aria-expanded.

CodeBlock.Icon

A small icon that represents the type of code block being displayed, rendered as an SVG next to the code block title in the code block header. You can pass in a custom SVG component or use one of the presets (you can exclusively pass one of svg or preset).

All props from Icon, plus:

CodeBlock.TabList

A tab list for the CodeBlock header. Renders pill-styled tab triggers that switch which code is displayed. Place this inside CodeBlock.Header and pair with CodeBlock.TabContent in CodeBlock.Body. CodeBlock.Root owns the tab state via defaultTab / activeTab / onActiveTabChange.

All props from standard HTML div attributes.

CodeBlock.TabTrigger

A pill-styled tab trigger for the CodeBlock header. Must be rendered within a CodeBlock.TabList.

All props from standard HTML button attributes, plus:

CodeBlock.TabContent

Conditionally renders its children when the associated tab is active. Pair with CodeBlock.TabList and CodeBlock.TabTrigger in the header, and set defaultTab / activeTab on CodeBlock.Root.

All props from standard HTML div attributes, plus:

jsonCodeBlockValue

Builds a MantleCodeBlockValue that renders any value as syntax-highlighted JSON entirely on the client — no Shiki runtime, build-time plugin, or server roundtrip (see Highlighting runtime JSON on the client). Pass the result to CodeBlock.Code's value prop. Serialization is safe and never throws: BigInt → decimal string, circular/repeated references → "[Circular]", and values that serialize to undefined → "".

1jsonCodeBlockValue(value: unknown, options?: JsonCodeBlockValueOptions): MantleCodeBlockValue

Byte-for-byte parity with server/build-time Shiki output is guaranteed for canonical JSON.stringify shapes — which is exactly what this function produces.

jsonToShikiHtml

The lower-level primitive behind jsonCodeBlockValue. Tokenizes a JSON string into the same CSS-variable-colored <code> inner HTML that Mantle's server/build-time Shiki highlighter produces, without shipping Shiki to the browser. Returns an HTML string with no line-number or fold decoration — feed it through decorateHighlightedHtml for that, as jsonCodeBlockValue does. Reach for it only when you need the raw markup; most consumers want jsonCodeBlockValue.

1jsonToShikiHtml(code: string): string