CodeBlock

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

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.

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.

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

{
  "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.