CodeBlock

The CodeBlock component provides syntax highlighting powered by Shiki, with support for line numbers, code wrapping, line highlighting, focus mode, expandable content, and copy-to-clipboard functionality.

Basic Usage

import { CodeBlock } from '@mintlify/components';

<CodeBlock language="javascript">
  {`console.log('Hello, World!');`}
</CodeBlock>

CodeBlock Props

language

string

The programming language for syntax highlighting (e.g., “javascript”, “python”, “java”). Supports all languages that Shiki supports.

lang

string

Alias for language prop.

filename

string

Display a filename in the code block header. When set, displays a header section with gray background.

icon

string

Icon to display in the code block header (e.g., “js”, “python”, “java”). Requires filename to be set to display the header.

lines

boolean

Enable line numbers on the left side of the code block.

wrap

boolean

Enable code wrapping instead of horizontal scrolling. Long lines will wrap to the next line.

expandable

boolean

Make the code block expandable/collapsible when content exceeds a certain height. Shows a “Show more/less” button at the bottom.

highlight

string

Lines to highlight as a JSON stringified array (e.g., "[1,3,4,5]"). Highlighted lines have a colored background.

focus

string

Lines to focus on (dims other lines) as a JSON stringified array (e.g., "[2,4,6]"). Non-focused lines are faded.

codeBlockTheme

'system' | 'dark'

default:"system"

The UI theme for the code block container (border, background, text color):

"system": Adapts to light/dark mode
"dark": Always uses dark theme

codeBlockThemeObject

CodeStyling

Custom syntax highlighting theme. Can be:

A string: "system" or "dark" for default themes
An object with a theme property for Shiki themes:
- Single theme: { theme: "dracula" }
- Dual themes: { theme: { light: "everforest-light", dark: "dracula" } }

isSmallText

boolean

Use smaller text size (text-xs instead of text-sm).

className

string

Additional CSS classes for the code block container.

copyButtonProps

CopyToClipboardButtonProps

Props to customize the copy button behavior and appearance. See Copy Button Props below.

children

ReactNode

The code content to display.

Copy Button Props

Whether to show the tooltip on hover.

copyButtonAriaLabel

string

default:"Copy the contents from the code block"

Aria label for the copy button for screen readers.

Text to display in the tooltip before copying.

Text to display in the tooltip after successful copy.

onCopied

(result: CopyToClipboardResult, textToCopy?: string) => void

Callback function called after copy attempt. Receives the copy result (“success” or “error”) and the copied text.

Examples

With Filename and Icon

<CodeBlock 
  filename="HelloWorld.java" 
  icon="java"
  language="java"
>
  {`class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}`}
</CodeBlock>

With Line Numbers

<CodeBlock 
  language="python"
  lines={true}
>
  {`def greet(name):
    return f"Hello, {name}!"

print(greet("World"))`}
</CodeBlock>

With Line Highlighting

Highlight specific lines to draw attention to important code:

<CodeBlock 
  language="javascript"
  lines={true}
  highlight={JSON.stringify([3, 5, 7])}
>
  {`function calculateSum(a, b) {
  // Validate inputs
  if (typeof a !== 'number' || typeof b !== 'number') {
    throw new Error('Arguments must be numbers');
  }
  // Calculate and return sum
  return a + b;
}

console.log(calculateSum(5, 3));`}
</CodeBlock>

With Focus Mode

Focus on specific lines while dimming others:

<CodeBlock 
  language="typescript"
  lines={true}
  focus={JSON.stringify([2, 3, 4])}
>
  {`interface User {
  id: string;
  name: string;
  email: string;
}

const user: User = {
  id: '123',
  name: 'John Doe',
  email: 'john@example.com'
};`}
</CodeBlock>

Highlight and Focus Combined

<CodeBlock 
  language="javascript"
  lines={true}
  highlight={JSON.stringify([2, 4, 6])}
  focus={JSON.stringify([1, 3, 5])}
>
  {`// This demonstrates both highlight and focus
const highlighted1 = true;
const focused1 = true;
const highlighted2 = true;
const focused2 = true;
const highlighted3 = true;`}
</CodeBlock>

With Code Wrapping

<CodeBlock 
  language="javascript"
  wrap={true}
  lines={true}
>
  {`const veryLongLine = "This is a very long line of code that would normally require horizontal scrolling, but with wrap enabled it will wrap to the next line instead.";`}
</CodeBlock>

Expandable Code Block

For long code snippets, enable expandable mode:

<CodeBlock 
  language="python"
  expandable={true}
  lines={true}
  filename="library.py"
>
  {`# Long Python code here...
class DataProcessor:
    def __init__(self):
        self.data = []
    
    def process(self, item):
        # Process logic
        pass
    
    # ... many more lines ...`}
</CodeBlock>

Custom Shiki Theme

Use any Shiki theme for syntax highlighting:

<CodeBlock 
  language="javascript"
  codeBlockThemeObject={{ theme: "dracula" }}
>
  {`const message = 'Using Dracula theme';
console.log(message);`}
</CodeBlock>

Dual Themes (Light/Dark)

Provide different themes for light and dark modes:

<CodeBlock 
  language="typescript"
  codeBlockThemeObject={{
    theme: { 
      light: "everforest-light", 
      dark: "dracula" 
    }
  }}
>
  {`type Theme = 'light' | 'dark';
const currentTheme: Theme = 'light';`}
</CodeBlock>

Language Support

CodeBlock supports syntax highlighting for hundreds of programming languages through Shiki, including: Popular Languages:

JavaScript, TypeScript, JSX, TSX
Python, Java, C++, C#, Go, Rust
Ruby, PHP, Swift, Kotlin, Scala
HTML, CSS, SCSS, LESS
SQL, GraphQL, JSON, YAML, TOML, XML

Shell & Config:

Bash, Shell, PowerShell, Zsh
Dockerfile, Docker Compose
Nginx, Apache
.env files, INI files

Frameworks & Tools:

React, Vue, Svelte, Angular
Markdown, MDX
Prisma, Protocol Buffers
Regular Expressions (regex)

Shiki uses TextMate grammars, the same as VS Code, ensuring accurate highlighting for virtually any language. If a language isn’t recognized, the code will display as plain text.

Available Shiki Themes

The component supports all standard Shiki themes including:

andromeeda, aurora-x, ayu-dark
catppuccin-frappe, catppuccin-latte, catppuccin-macchiato, catppuccin-mocha
dark-plus, dracula, dracula-soft
everforest-dark, everforest-light
github-dark, github-dark-default, github-dark-dimmed, github-dark-high-contrast
github-light, github-light-default, github-light-high-contrast
gruvbox-dark-hard, gruvbox-dark-medium, gruvbox-dark-soft
gruvbox-light-hard, gruvbox-light-medium, gruvbox-light-soft
houston, kanagawa-dragon, kanagawa-lotus, kanagawa-wave
laserwave, light-plus, material-theme, material-theme-darker
material-theme-lighter, material-theme-ocean, material-theme-palenight
min-dark, min-light, monokai, night-owl, nord
one-dark-pro, one-light, plastic, poimandres
red, rose-pine, rose-pine-dawn, rose-pine-moon
slack-dark, slack-ochin, snazzy-light
solarized-dark, solarized-light, synthwave-84
tokyo-night, vesper, vitesse-black, vitesse-dark, vitesse-light
css-variables

Copy to Clipboard

The CodeBlock automatically includes a copy-to-clipboard button that:

Appears in the top-right corner
Shows a tooltip on hover (“Copy” / “Copied!”)
Hides if the clipboard API is unavailable
Can be customized via copyButtonProps

Customizing Copy Button

<CodeBlock 
  language="javascript"
  copyButtonProps={{
    showTooltip: false,
    copyButtonAriaLabel: "Copy code to clipboard",
    tooltipCopyText: "Copy code",
    tooltipCopiedText: "Copied successfully!",
    onCopied: (result, text) => {
      console.log('Copy result:', result);
      if (result === 'success') {
        // Track copy event
        analytics.track('code_copied', { language: 'javascript' });
      }
    }
  }}
>
  {`const code = 'example';`}
</CodeBlock>

Advanced Examples

All Features Combined

<CodeBlock 
  filename="advanced-example.ts"
  icon="typescript"
  language="typescript"
  lines={true}
  highlight={JSON.stringify([5, 6, 7, 8, 9])}
  focus={JSON.stringify([10, 11, 12, 13])}
  expandable={true}
  codeBlockTheme="dark"
  codeBlockThemeObject={{ theme: "dracula" }}
  copyButtonProps={{
    onCopied: (result) => console.log('Copied:', result)
  }}
>
  {`// TypeScript example with all features
interface Config {
  port: number;
  host: string;
}

// This section is highlighted
const config: Config = {
  port: 3000,
  host: 'localhost'
};

// This section is focused
function startServer(config: Config) {
  console.log(\`Server starting on \${config.host}:\${config.port}\`);
  return true;
}

// More code to make it expandable
const result = startServer(config);
console.log('Server started:', result);`}
</CodeBlock>

Responsive Code Blocks

Adjust text size for mobile devices:

<CodeBlock 
  language="javascript"
  isSmallText={true}
  wrap={true}
  filename="mobile-friendly.js"
>
  {`// Smaller text and wrapping for mobile devices
const responsive = true;
console.log('Optimized for smaller screens');`}
</CodeBlock>

Accessibility

The copy button includes proper aria-label attributes
Code blocks use semantic HTML with proper lang attributes
Keyboard navigation is fully supported
Focus indicators are visible and clear

BaseCodeBlock

The BaseCodeBlock component is a lower-level component that CodeBlock is built on. It provides the core syntax highlighting functionality without the header and copy button.

BaseCodeBlock Props

All CodeBlock props plus:

isParentCodeGroup

boolean

Internal prop used when rendered inside a CodeGroup. Adjusts height and overflow behavior.

shouldHighlight

boolean

default:"true"

Whether to apply syntax highlighting. Set to false to skip highlighting for performance.

forceExtract

boolean

default:"false"

Force extraction of code string from children in specific scenarios.

Usage

import { BaseCodeBlock } from '@mintlify/components';

<BaseCodeBlock 
  language="javascript"
  lines={true}
>
  {`console.log('Hello, World!');`}
</BaseCodeBlock>

Most developers should use CodeBlock instead, which includes the copy button and header functionality.

Diff Syntax Support

CodeBlocks support diff syntax for showing code changes:

<CodeBlock language="javascript" lines={true}>
  {`function example() {
-  const oldValue = 123;
+  const newValue = 456;
   
-  return oldValue;
+  return newValue;
}`}
</CodeBlock>

Lines starting with - will be highlighted as removed (red), and lines starting with + will be highlighted as added (green).

Notes

The component uses Shiki for syntax highlighting, providing accurate, language-aware highlighting
Line highlighting and focus can be combined for powerful code demonstrations
The expandable feature automatically calculates height based on content
When using filename or icon, the code block displays a header section
The fade overlay (gradient edge effect) is disabled when using wrap, highlight, focus, or expandable
Copy button automatically hides if the browser doesn’t support the Clipboard API (non-HTTPS contexts)
Syntax highlighting is powered by Shiki, the same highlighter used by VS Code
The component supports both light and dark themes with automatic theme switching

Layout

Content

Code

Data Display

Visualization

Utility

Basic Usage

CodeBlock Props

Copy Button Props

Examples

With Filename and Icon

With Line Numbers

With Line Highlighting

With Focus Mode

Highlight and Focus Combined

With Code Wrapping

Expandable Code Block

Custom Shiki Theme

Dual Themes (Light/Dark)

Language Support

Available Shiki Themes

Copy to Clipboard

Customizing Copy Button

Advanced Examples

All Features Combined

Responsive Code Blocks

Accessibility

BaseCodeBlock

BaseCodeBlock Props

Usage

Diff Syntax Support

Notes

Layout

Content

Code

Data Display

Visualization

Utility

Documentation Index

​Basic Usage

​CodeBlock Props

​Copy Button Props

​Examples

​With Filename and Icon

​With Line Numbers

​With Line Highlighting

​With Focus Mode

​Highlight and Focus Combined

​With Code Wrapping

​Expandable Code Block

​Custom Shiki Theme

​Dual Themes (Light/Dark)

​Language Support

​Available Shiki Themes

​Copy to Clipboard

​Customizing Copy Button

​Advanced Examples

​All Features Combined

​Responsive Code Blocks

​Accessibility

​BaseCodeBlock

​BaseCodeBlock Props

​Usage

​Diff Syntax Support

​Notes

Basic Usage

CodeBlock Props

Copy Button Props

Examples

With Filename and Icon

With Line Numbers

With Line Highlighting

With Focus Mode

Highlight and Focus Combined

With Code Wrapping

Expandable Code Block

Custom Shiki Theme

Dual Themes (Light/Dark)

Language Support

Available Shiki Themes

Copy to Clipboard

Customizing Copy Button

Advanced Examples

All Features Combined

Responsive Code Blocks

Accessibility

BaseCodeBlock

BaseCodeBlock Props

Usage

Diff Syntax Support

Notes