How to Add Live Code Blocks in Docusaurus: Complete Guide to the theme-live-codeblock Plugin

You can add live code blocks to Docusaurus by installing the @docusaurus/theme-live-codeblock package, registering it in the themes array of your docusaurus.config.js, and writing fenced code blocks with the jsx or tsx language identifier.

The facebook/docusaurus repository provides a dedicated theme package that transforms static JSX examples into interactive, editable playgrounds powered by react-live. This integration allows documentation readers to modify component code in real-time and see immediate results without leaving the page.

Installation and Configuration

To add live code blocks to your Docusaurus site, you must install the theme package and register it as a theme rather than a standard plugin.

Step 1: Install the Package

Add @docusaurus/theme-live-codeblock to your project dependencies:

npm install --save @docusaurus/theme-live-codeblock

Or using Yarn:

yarn add @docusaurus/theme-live-codeblock

Step 2: Register the Theme

Open your docusaurus.config.js file and add the package to the themes array. Unlike plugins, themes belong in the themes configuration key:

// docusaurus.config.js
module.exports = {
  title: 'My Site',
  url: 'https://example.com',
  baseUrl: '/',
  themes: [
    '@docusaurus/theme-classic',
    // Add the live-codeblock theme
    '@docusaurus/theme-live-codeblock',
  ],
};

Creating Live Code Blocks in Markdown

Once the theme is registered, Docusaurus automatically converts fenced code blocks with specific language identifiers into interactive playgrounds.

Supported Language Identifiers

Use jsx for JavaScript React components or tsx for TypeScript React components:

```jsx
export default function Counter() {
  const [count, setCount] = React.useState(0);
  return (
    <button onClick={() => setCount(count + 1)}>
      Clicked {count} {count === 1 ? 'time' : 'times'}
    </button>
  );
}

When rendered, this block displays an editable code editor on the left and a live preview on the right. Any code changes immediately update the preview without page reload.

## Architecture and How It Works

The live code block functionality relies on a component-swizzling architecture that overrides Docusaurus's default code rendering behavior.

### Component Hierarchy

The theme operates through three primary components located in `packages/docusaurus-theme-live-codeblock/src/theme/`:

**[`CodeBlock/index.tsx`](https://github.com/facebook/docusaurus/blob/main/CodeBlock/index.tsx)**

This component overrides the default Docusaurus `CodeBlock`. It inspects the `language` prop and delegates to `LiveCodeBlock` when the language is `jsx` or `tsx`. For other languages, it falls back to the standard static code block.

**[`LiveCodeBlock/index.tsx`](https://github.com/facebook/docusaurus/blob/main/LiveCodeBlock/index.tsx)**

The core implementation that creates a `react-live` `<LiveProvider>` with the code string and optional scope. It renders the `Playground` component containing the editor interface and preview pane.

**[`ReactLiveScope/index.tsx`](https://github.com/facebook/docusaurus/blob/main/ReactLiveScope/index.tsx)**

Defines the default execution scope for live blocks. By default, it exports only `React`. You can swizzle this component to inject custom components, hooks, or utilities that become available in every live code block without explicit imports.

### Runtime Execution Flow

1. Docusaurus parses Markdown and creates a `CodeBlock` element for each fenced block
2. The theme-registered `CodeBlock` component detects `jsx` or `tsx` languages
3. It renders `LiveCodeBlock`, which initializes `react-live` with the code content
4. The `Playground` component renders the Monaco-style editor and live preview
5. User edits trigger immediate recompilation and preview updates in an isolated scope

## Customizing the Live Environment

You can extend the live code block functionality by exposing custom components or utilities to the execution scope.

### Swizzling ReactLiveScope

To make your own components available in every live block without repetitive imports, swizzle the `ReactLiveScope` component:

```bash
npx docusaurus swizzle @docusaurus/theme-live-codeblock ReactLiveScope --eject

This generates src/theme/ReactLiveScope/index.tsx in your project. Edit this file to import and export your custom components:

import React from 'react';
import MyButton from '../../components/MyButton';
import { useCustomHook } from '../../hooks/useCustomHook';

export default {
  React,
  MyButton,
  useCustomHook,
};

Now any live code block can use <MyButton /> or useCustomHook() directly:

export default function Demo() {
  const data = useCustomHook();
  return <MyButton>{data}</MyButton>;
}

Summary

• Install @docusaurus/theme-live-codeblock via npm or Yarn to add live code block capabilities to your Docusaurus site
• Register the package in the themes array of docusaurus.config.js, not the plugins array
• Write fenced code blocks with jsx or tsx language identifiers to automatically render interactive playgrounds
• Customize the execution scope by swizzling ReactLiveScope to expose custom components and hooks across all live blocks
• Understand that the implementation relies on component swizzling in packages/docusaurus-theme-live-codeblock/src/theme/ to override default code block rendering with react-live integration

Frequently Asked Questions

What is the difference between a Docusaurus plugin and theme for live code blocks?

Docusaurus themes are specialized packages that can override default components through the swizzling system, while plugins typically add functionality without replacing core UI components. The @docusaurus/theme-live-codeblock package must be registered in the themes array because it overrides the default CodeBlock component in packages/docusaurus-theme-live-codeblock/src/theme/CodeBlock/index.tsx to detect JSX/TSX languages and delegate to the live implementation.

Can I use TypeScript in live code blocks?

Yes, you can use TypeScript by specifying the tsx language identifier in your fenced code block. The CodeBlock component in packages/docusaurus-theme-live-codeblock/src/theme/CodeBlock/index.tsx recognizes both jsx and tsx as valid languages for live rendering, passing the code content to the LiveCodeBlock component which processes it through react-live.

How do I expose my own React components to every live code block?

Swizzle the ReactLiveScope component using the command npx docusaurus swizzle @docusaurus/theme-live-codeblock ReactLiveScope --eject. This creates a local copy of src/theme/ReactLiveScope/index.tsx in your project where you can import and export any components, hooks, or utilities. These exports become available in the global scope of every live code block without requiring explicit import statements in the block itself.

Why are my JSX code blocks still showing as static code instead of live editors?

This typically happens when the @docusaurus/theme-live-codeblock package is registered in the plugins array instead of the themes array in docusaurus.config.js, or when the language identifier is not exactly jsx or tsx. The component swizzling mechanism only activates when the package is listed under themes, and the CodeBlock component specifically checks for these language strings to determine whether to render the LiveCodeBlock component or fall back to static rendering.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}