CodeBlock renders syntax-highlighted code with line numbers, a copy button, and optional collapsible sections. Use CodeBlock for multi-line snippets like source files, terminal commands, and configuration examples. Use Code for inline references to function names, variables, or CLI flags within body text.
ts
| Guidance | Practices |
|---|---|
| Do | Set the language prop to match the code content so syntax highlighting is accurate. Use "plaintext" when the language is unknown. |
| Do | Add a title when the code represents a file. It gives readers context and appears in the header bar alongside the copy button. |
| Do | Use Code for short inline references like function names or CLI flags, and CodeBlock for standalone multi-line snippets. |
| Don't | Enable line numbers on short snippets (under 5 lines) where they add clutter without helping navigation. |
| Don't | Nest a code block inside a scrollable container. Use the maxHeight prop instead, which handles overflow natively. |
Short terminal commands with a copy button and no line numbers. Use for install instructions or one-liner commands that readers will paste directly.
TypeScript code with specific lines highlighted to draw attention to a key section. Use highlightLines to call out new or important code in tutorials and changelogs.
A JSON configuration file with a title bar and line numbers. The title prop adds a filename label in the header so readers know which file the code belongs to.
A long code block with a max height that enables vertical scrolling. Use maxHeight to keep the block from dominating the page when displaying large files.