Code Block (Dynamic)

Fumadocs

Shiki

Hast

Open in

Loading component...

Installation

Usage

The Dynamic Code Block component provides server-side syntax highlighting using Shiki, with better performance and more accurate highlighting than client-side solutions:

import { 
  CodeBlock, 
  Pre, 
  DynamicCodeBlock 
} from '@/components/redpanda-ui/code-block-dynamic';

// Basic usage with automatic syntax highlighting
const sampleCode = `function greetUser(name: string): string {
  return \`Hello, \${name}! Welcome to Redpanda UI.\`;
}`;

export function Example() {
  return (
    <DynamicCodeBlock
      lang="typescript"
      code={sampleCode}
      options={{
        title: "greet.ts",
        icon: "📄",
        allowCopy: true,
        theme: { light: "github-light", dark: "github-dark" }
      }}
    />
  );
}

// Advanced usage with custom theming and line numbers
export function AdvancedExample() {
  return (
    <DynamicCodeBlock
      lang="typescript"
      code={sampleCode}
      options={{
        title: "greet.ts",
        icon: "📄",
        allowCopy: true,
        keepBackground: true,
        'data-line-numbers': true,
        'data-line-numbers-start': 1,
        themes: {
          light: "catppuccin-latte",
          dark: "catppuccin-mocha"
        },
        components: {
          // Custom component overrides
          pre: (props) => <Pre className="custom-pre" {...props} />
        }
      }}
    />
  );
}

// Manual CodeBlock usage for custom highlighting
export function ManualExample() {
  return (
    <CodeBlock 
      title="config.json" 
      icon="⚙️"
      allowCopy={true}
      keepBackground={false}
      data-line-numbers={true}
    >
      <Pre>
        <code className="language-json">
          {JSON.stringify({ theme: "dark", fontSize: 14 }, null, 2)}
        </code>
      </Pre>
    </CodeBlock>
  );
}

When to use

Use this decision tree to determine when to use the Dynamic Code Block component over the regular Code Block:

Use Cases

Documentation sites: Technical documentation with accurate syntax highlighting
Code tutorials: Step-by-step programming guides with proper code display
API references: Code examples with language-specific highlighting
Blog posts: Technical articles with multiple code examples
Code showcases: Portfolio or demonstration code with professional presentation

Dynamic Code Block vs Regular Code Block

Use Dynamic Code Block when: You need server-side syntax highlighting, accurate language support, custom themes, or better performance with many code blocks
Use regular Code Block when: Client-side highlighting is sufficient, you have simple highlighting needs, or you're not using SSR
Use inline <code> when: Short code snippets within text content
Use Code Editor when: Users need to edit or interact with the code

Anatomy

The Dynamic Code Block component extends the regular Code Block with Shiki-powered syntax highlighting:

Dynamic Code Block Architecture:
┌─────────────────────────────────────────────────┐
│ DynamicCodeBlock (Wrapper Component)            │
│ ┌─────────────────────────────────────────────┐ │
│ │ useShiki Hook                               │ │
│ │ - Server-side syntax highlighting           │ │
│ │ - Theme management (light/dark)             │ │
│ │ - Language detection and parsing            │ │
│ │ - Component transformation                  │ │
│ └─────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Loading Fallback                            │ │
│ │ - Plain text display during SSR            │ │
│ │ - Line-by-line structure preserved         │ │
│ │ - Prevents layout shift                     │ │
│ └─────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────┐ │
│ │ CodeBlock (Enhanced Container)              │ │
│ │ ┌─────────────────────────────────────────┐ │ │
│ │ │ Header (with enhanced styling)          │ │ │
│ │ │ [Icon] Title Text [CopyButton]          │ │ │
│ │ │ - keepBackground option                 │ │ │
│ │ │ - Custom icon support                   │ │ │
│ │ └─────────────────────────────────────────┘ │ │
│ │ ┌─────────────────────────────────────────┐ │ │
│ │ │ Viewport (Scroll Container)             │ │ │
│ │ │ ┌─────────────────────────────────────┐ │ │ │
│ │ │ │ Pre (Syntax Highlighted)            │ │ │ │
│ │ │ │ ┌─────────────────────────────────┐ │ │ │ │
│ │ │ │ │ Line Elements                   │ │ │ │ │
│ │ │ │ │ - span.line containers          │ │ │ │ │
│ │ │ │ │ - Token-based highlighting      │ │ │ │ │  
│ │ │ │ │ - Line number support           │ │ │ │ │
│ │ │ │ │ - Counter-based numbering       │ │ │ │ │
│ │ │ │ └─────────────────────────────────┘ │ │ │ │
│ │ │ └─────────────────────────────────────┘ │ │ │
│ │ └─────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────┐ │
│ │ CopyButton (Enhanced)                       │ │
│ │ - Animated check/copy icons                 │ │
│ │ - Smart text extraction                     │ │
│ │ - Hover state management                    │ │
│ │ - Accessibility features                    │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

Shiki Integration Flow:
┌─────────────────────────────────────┐
│ Code String + Language              │
│ ↓                                   │
│ Shiki Highlighter                   │
│ - Tokenizes syntax                  │
│ - Applies theme colors              │
│ - Generates HAST tree               │
│ ↓                                   │
│ HAST to JSX Runtime                 │
│ - Converts to React elements        │
│ - Preserves syntax structure        │ 
│ - Applies custom components         │
│ ↓                                   │
│ Rendered Highlighted Code           │
└─────────────────────────────────────┘

Component Composition

DynamicCodeBlock: Main wrapper orchestrating syntax highlighting
useShiki Hook: Custom hook managing Shiki highlighting and SSR
CodeBlock: Enhanced container with dynamic theme support
Pre: Structured preformatted text element with line support
CopyButton: Advanced copy functionality with visual feedback
Theme Management: Automatic light/dark theme switching
Line Numbers: CSS counter-based line numbering system
Component Override: Customizable rendering via components prop
Performance: Server-side rendering with client hydration

Examples

Default