# CodeBlock

- Page: https://jiguang132.com/resources/astryx/docs/code-block
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

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.

## Installation

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

Requires React 19+, base CSS and a Theme provider. See [Setup](/resources/astryx/docs/getting-started).

## Code Block

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.

| Prop | Type | Default | Description |
|---|---|---|---|
| code * | string |  | The code string to display. |
| language | string | 'plaintext' | Language for syntax highlighting. Use "plaintext" to disable. |
| title | string |  | Filename or label shown in the header bar. |
| hasLanguageLabel | boolean | true | Show the language name in the header bar. Hidden when language is "plaintext". |
| hasLineNumbers | boolean | false | Show a line number gutter. |
| highlightLines | number[] |  | 1-indexed line numbers to highlight. |
| isDiff | boolean | false | Render the code as a unified diff over `language`: lines starting with + are added, - removed, @@ is a hunk header (a `--- `/`+++ ` file-header pair directly before one is a header too), anything else is context. The language label reads `diff` or `<language> diff`. The glyph sits in its own column and the rest of each line keeps syntax highlighting; copy returns the exact source. Markdown ```diff and ```diff-<lang> fences set this. |
| hasCopyButton | boolean | true | Show a copy-to-clipboard button. |
| onCopy | () => void |  | Callback after the code is copied. |
| isWrapped | boolean | false | Wrap long lines instead of enabling horizontal scroll. |
| maxHeight | number \| string |  | Max height before the block scrolls vertically. |
| size | 'sm' \| 'md' | 'md' | Text size variant. |
| width | string | 'fit-content' | Width of the code block. Any CSS width value. 'fit-content' (default) shrinks to longest line. '100%' fills parent width. |
| container | 'card' \| 'section' | 'card' | Container presentation style. 'card' (default): border and radius with the muted syntax background for a standalone card look. 'section': no border or radius and a transparent background so the block blends into the card or panel it's embedded in. |
| tokenizer | (code: string, language: string) => Array<{type: string; start: number; end: number}> |  | Custom tokenizer override for unsupported languages. |
| syntaxTheme | SyntaxThemeDefinition |  | Per-instance syntax theme override. Shorthand for wrapping the block in <SyntaxTheme theme={...}>. Accepts a preset from @astryxdesign/core/theme/syntax or a theme created with defineSyntaxTheme(). Defaults to the nearest SyntaxTheme ancestor or the theme-level syntax colors. |
| highlightMode | 'auto' \| 'ranges' \| 'spans' | 'auto' | Syntax highlighting rendering mode. |
| isCollapsible | boolean | false | Allow collapsing the code body into just the header bar. Starts expanded; a visible header becomes clickable when the code exceeds collapsibleThreshold lines. Headerless blocks never collapse, and removing the header expands a previously collapsed block. |
| collapsibleThreshold | number | 10 | Minimum number of lines before the collapse toggle appears. Below this threshold the code block renders normally even when isCollapsible is true. |
| ref | React.Ref<HTMLPreElement> |  | Ref forwarded to the root code-block element. |
| xstyle | StyleXStyles |  | StyleX styles for layout customization. Must be a stylex.create() value. |
| className | string |  | CSS class name for the root element. Prefer xstyle for styling. |
| style | CSSProperties |  | Inline styles. Prefer xstyle for StyleX-optimized styling. |
| data-testid | string |  | Test selector for automated testing frameworks. |

### Usage guidance

- Set the language prop to match the code content so syntax highlighting is accurate. Use "plaintext" when the language is unknown.
- Add a title when the code represents a file. It gives readers context and appears in the header bar alongside the copy button.
- Use Code for short inline references like function names or CLI flags, and CodeBlock for standalone multi-line snippets.
- Avoid: Enable line numbers on short snippets (under 5 lines) where they add clutter without helping navigation.
- Avoid: Nest a code block inside a scrollable container. Use the maxHeight prop instead, which handles overflow natively.

### Theming API

```json
{
  "targets": [
    {
      "className": "astryx-code-block",
      "visualProps": [
        "size",
        "language",
        "container"
      ]
    },
    {
      "className": "astryx-code-block-header",
      "visualProps": [
        "size",
        "language",
        "container"
      ]
    },
    {
      "className": "astryx-code-block-title",
      "visualProps": [
        "size",
        "language"
      ]
    },
    {
      "className": "astryx-code-block-copy-button"
    }
  ],
  "vars": [
    {
      "name": "--_codeblock-gutter-width",
      "description": "Width of the line-number gutter, computed from the digit count of the last line so the code column starts at a stable offset.",
      "default": "2ch",
      "private": true
    }
  ]
}
```

## Code



### Anatomy

- **Header Bar**: Shows the title, visible language label, and copy button when a header is present. A title or visible language label creates the header; the copy button alone floats at the top-end of a headerless block.
- **Header Title**: Groups the optional title, visible language label, and collapsible chevron inside the header bar.
- **Line Numbers**: Numbered gutter along the left edge. Enable with hasLineNumbers.
- **Code Body**: The syntax-highlighted code content.
- **Highlighted Lines**: Background accent on specific lines to draw attention.
- **Copy Button**: Copies the code string to the clipboard. Shown by default.


## Examples

- Code Block: A syntax-highlighted TypeScript code block with line numbers, a title bar, and a copy button.
- Code — Snippet: Short terminal commands with a copy button and no line numbers. Use for install instructions or one-liner commands that readers will paste directly.
- Code — Highlighted: 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.
- Code — Config: 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.
- Code — Scrollable: 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.
- Code — Terminal: A dark terminal-style command block: a bash CodeBlock wrapped in SyntaxTheme with the GitHub Dark preset, copy button on, and no line numbers. Use for shell sessions or CLI output that should read as a terminal even on light pages. Reach for a dark syntax preset instead of hand-rolling a dark box with custom CSS.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt