CodeBlock
<CodeBlock> wraps a shiki-rendered <pre> with the docs-template
header bar: a language chip, an optional filename, a :set nu
line-number toggle, and a copy button. You rarely use it directly —
every fenced code block in MDX gets it automatically via the pre
mapping in the MDX component map.
Automatic usage (fenced blocks)
renders as:
The file="…" meta string becomes the filename chip; the fence
language becomes the language chip. Both are extracted by the shiki
config inside dockit().
Floating controls
Without a filename, the controls sit over the code. A soft, theme-matched background blurs and fades the text beneath the language label, line-number toggle, and copy button. The controls stay sharp and appear on hover or keyboard focus without shifting the code.
Direct usage
For code you render outside MDX (or source you already have as a string), compose it yourself:
Props
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | A <pre><code> tree (usually shiki output). |
filename | string | — | Filename chip in the header bar. |
lang | string | — | Language chip. Auto-forwarded from the fence language in MDX. |
Behavior notes
- The header bar only renders when
filenameis set. Without afile="…"meta string, the language chip, line-number toggle, and copy button float in the top-right corner and reveal on hover (or keyboard focus) instead — compare the two fenced blocks above. - The line-number toggle is site-wide state
(
useLineNumbers) — flipping it in one block flips every block, including the Source tabs of<Preview>frames. - Copy grabs the text content of the inner
<code>element. - A successful copy pops a few of the copied code's own punctuation marks
(
{ } ( ) ;…) out of the button in its ink and mono face; they arc and fade in under a second inside a fixed overlay that removes itself, so nothing reflows. Reduced-motion preferences skip it and keep only theCopiedlabel. Code tabs and<Preview>source copies behave the same. - Colors come from the shiki dual theme (github-light / github-dark) and follow the site theme with no re-render — see Theming.