XDS — Design System

CodeBlock@xds/core · XDSCodeBlock v0.0.13

Usage

CodeBlock renders syntax-highlighted code with line numbers, a copy button, and optional collapsible sections. Use XDSCodeBlock for multi-line snippets like source files, terminal commands, and configuration examples. Use XDSCode for inline references to function names, variables, or CLI flags within body text.

ts
import {XDSCodeBlock} from '@xds/core/CodeBlock'

Best practices

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 XDSCode for short inline references like function names or CLI flags, and XDSCodeBlock 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.

Sub-components

CodeBlock is a compound component with 2 sub-components.

XDSCode

Inline code element. Renders a styled <code> with monospace font and muted background. For fenced blocks, use XDSCodeBlock.

Prop	Type	Description
childrenrequired	ReactNode	Code content.
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.

XDSCodeBlock

Fenced code block with syntax highlighting. Use for multi-line code snippets.

Prop	Type	Description
coderequired	string	The code string to display.
language	string (default: 'plaintext')	Language for syntax highlighting. Use "plaintext" to disable.
title	string	Filename or label shown in the header bar.
hasLanguageLabel	boolean (default: true)	Show the language name in the header bar. Hidden when language is "plaintext".
hasLineNumbers	boolean (default: false)	Show a line number gutter.
highlightLines	number[]	1-indexed line numbers to highlight.
hasCopyButton	boolean (default: true)	Show a copy-to-clipboard button.
onCopy	() => void	Callback after the code is copied.
isWrapped	boolean (default: false)	Wrap long lines instead of enabling horizontal scroll.
maxHeight	number \| string	Max height before the block scrolls vertically.
size	'sm' \| 'md' (default: 'md')	Text size variant.
tokenizer	(code: string, language: string) => Array<{type: string; start: number; end: number}>	Custom tokenizer override for unsupported languages.
isCollapsible	boolean (default: false)	Allow collapsing the code body into just the header bar. Starts expanded; the header becomes clickable to toggle. Only shows the toggle when the code exceeds collapsibleThreshold lines.
collapsibleThreshold	number (default: 10)	Minimum number of lines before the collapse toggle appears. Below this threshold the code block renders normally even when isCollapsible is true.
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.

Examples

Common configurations, variations, and states.

Code — ConfigA 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.

tsx
'use client';
import {XDSCodeBlock} from '@xds/core/CodeBlock';
const code = `{
  "name": "@xds/core",
  "version": "0.0.5",
  "dependencies": {
    "@stylexjs/stylex": "^0.17.5",
    "react": "^19.0.0"
  },
  "scripts": {
    "build": "tsup",
    "test": "vitest"
  }
}`;
export default function CodeBlockJSONConfig() {
  return (
    <XDSCodeBlock
      code={code}
      language="json"
      title="package.json"
      hasLineNumbers
    />
  );
}

Code — HighlightedTypeScript 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.

tsx
'use client';
import {XDSCodeBlock} from '@xds/core/CodeBlock';
const code = `import {useState, useEffect} from 'react';
interface User {
  id: string;
  name: string;
  email: string;
}
async function fetchUser(id: string): Promise<User> {
  const response = await fetch(\`/api/users/\${id}\`);
  if (!response.ok) {
    throw new Error(\`HTTP \${response.status}\`);
  }
  return response.json();
}
export function useUser(id: string) {
  const [user, setUser] = useState<User | null>(null);
  useEffect(() => {
    fetchUser(id).then(setUser);
  }, [id]);
  return user;
}`;
export default function CodeBlockHighlightedLines() {
  return (
    <XDSCodeBlock
      code={code}
      language="typescript"
      title="useUser.ts"
      hasLineNumbers
      highlightLines={[9, 10, 11, 12, 13]}
    />
  );
}

Code — ScrollableA 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.

tsx
'use client';
import {XDSCodeBlock} from '@xds/core/CodeBlock';
const code = Array.from(
  {length: 50},
  (_, i) => `const line${i + 1} = ${i + 1};`,
).join('\n');
export default function CodeBlockScrollableBlock() {
  return (
    <XDSCodeBlock
      code={code}
      language="typescript"
      title="many-lines.ts"
      hasLineNumbers
      maxHeight="100%"
    />
  );
}

Code — SnippetShort terminal commands with a copy button and no line numbers. Use for install instructions or one-liner commands that readers will paste directly.

tsx
'use client';
import {XDSCodeBlock} from '@xds/core/CodeBlock';
import {XDSVStack} from '@xds/core/Stack';
export default function CodeBlockBashCommand() {
  return (
    <XDSVStack gap={4}>
      <XDSCodeBlock
        code="npm install @xds/core @stylexjs/stylex"
        language="bash"
        hasCopyButton
      />
      <XDSCodeBlock
        code={`curl -s https://api.example.com/status | jq '.services[] | select(.healthy == false)'`}
        language="bash"
        hasCopyButton
      />
    </XDSVStack>
  );
}

Showcase source

tsx
'use client';
import {XDSCodeBlock} from '@xds/core/CodeBlock';
const code = `import {useState, useEffect} from 'react';
export function useUser(id: string) {
  const [user, setUser] = useState<User | null>(null);
  useEffect(() => {
    fetch(\`/api/users/\${id}\`)
      .then(res => res.json())
      .then(setUser);
  }, [id]);
  return user;
}`;
export default function CodeBlockShowcase() {
  return (
    <XDSCodeBlock
      code={code}
      language="typescript"
      title="useUser.ts"
      hasLineNumbers
      hasCopyButton
    />
  );
}

Usage

import {XDSCodeBlock} from '@xds/core/CodeBlock'

Best practices

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 XDSCode for short inline references like function names or CLI flags, and XDSCodeBlock 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.

Prop

Type

Description

childrenrequired

ReactNode

Code content.

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.

Prop

Type

Description

coderequired

string

The code string to display.

language

string (default: 'plaintext')

Language for syntax highlighting. Use "plaintext" to disable.

title

string

Filename or label shown in the header bar.

hasLanguageLabel

boolean (default: true)

Show the language name in the header bar. Hidden when language is "plaintext".

hasLineNumbers

boolean (default: false)

Show a line number gutter.

highlightLines

number[]

1-indexed line numbers to highlight.

hasCopyButton

boolean (default: true)

Show a copy-to-clipboard button.

onCopy

() => void

Callback after the code is copied.

isWrapped

boolean (default: false)

Wrap long lines instead of enabling horizontal scroll.

maxHeight

number | string

Max height before the block scrolls vertically.

size

'sm' | 'md' (default: 'md')

Text size variant.

tokenizer

(code: string, language: string) => Array<{type: string; start: number; end: number}>

Custom tokenizer override for unsupported languages.

isCollapsible

boolean (default: false)

Allow collapsing the code body into just the header bar. Starts expanded; the header becomes clickable to toggle. Only shows the toggle when the code exceeds collapsibleThreshold lines.

collapsibleThreshold

number (default: 10)

Minimum number of lines before the collapse toggle appears. Below this threshold the code block renders normally even when isCollapsible is true.

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.

tsx

'use client'; import {XDSCodeBlock} from '@xds/core/CodeBlock'; const code = `{ "name": "@xds/core", "version": "0.0.5", "dependencies": { "@stylexjs/stylex": "^0.17.5", "react": "^19.0.0" }, "scripts": { "build": "tsup", "test": "vitest" } }`; export default function CodeBlockJSONConfig() { return ( <XDSCodeBlock code={code} language="json" title="package.json" hasLineNumbers /> ); }

tsx

'use client'; import {XDSCodeBlock} from '@xds/core/CodeBlock'; const code = `import {useState, useEffect} from 'react'; interface User { id: string; name: string; email: string; } async function fetchUser(id: string): Promise<User> { const response = await fetch(\`/api/users/\${id}\`); if (!response.ok) { throw new Error(\`HTTP \${response.status}\`); } return response.json(); } export function useUser(id: string) { const [user, setUser] = useState<User | null>(null); useEffect(() => { fetchUser(id).then(setUser); }, [id]); return user; }`; export default function CodeBlockHighlightedLines() { return ( <XDSCodeBlock code={code} language="typescript" title="useUser.ts" hasLineNumbers highlightLines={[9, 10, 11, 12, 13]} /> ); }

tsx

'use client'; import {XDSCodeBlock} from '@xds/core/CodeBlock'; const code = Array.from( {length: 50}, (_, i) => `const line${i + 1} = ${i + 1};`, ).join('\n'); export default function CodeBlockScrollableBlock() { return ( <XDSCodeBlock code={code} language="typescript" title="many-lines.ts" hasLineNumbers maxHeight="100%" /> ); }

tsx

'use client'; import {XDSCodeBlock} from '@xds/core/CodeBlock'; import {XDSVStack} from '@xds/core/Stack'; export default function CodeBlockBashCommand() { return ( <XDSVStack gap={4}> <XDSCodeBlock code="npm install @xds/core @stylexjs/stylex" language="bash" hasCopyButton /> <XDSCodeBlock code={`curl -s https://api.example.com/status | jq '.services[] | select(.healthy == false)'`} language="bash" hasCopyButton /> </XDSVStack> ); }

tsx

'use client'; import {XDSCodeBlock} from '@xds/core/CodeBlock'; const code = `import {useState, useEffect} from 'react'; export function useUser(id: string) { const [user, setUser] = useState<User | null>(null); useEffect(() => { fetch(\`/api/users/\${id}\`) .then(res => res.json()) .then(setUser); }, [id]); return user; }`; export default function CodeBlockShowcase() { return ( <XDSCodeBlock code={code} language="typescript" title="useUser.ts" hasLineNumbers hasCopyButton /> ); }