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

> Learn to add live code blocks in Docusaurus with the theme live codeblock plugin. Follow our easy guide to integrate interactive code examples into your documentation.

- Repository: [Meta/docusaurus](https://github.com/facebook/docusaurus)
- Tags: how-to-guide
- Published: 2026-03-04

---

**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`](https://github.com/facebook/docusaurus/blob/main/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:

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

```

Or using Yarn:

```bash
yarn add @docusaurus/theme-live-codeblock

```

### Step 2: Register the Theme

Open your [`docusaurus.config.js`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.js) file and add the package to the `themes` array. Unlike plugins, themes belong in the `themes` configuration key:

```js
// 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:

```markdown

```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`](https://github.com/facebook/docusaurus/blob/main/src/theme/ReactLiveScope/index.tsx) in your project. Edit this file to import and export your custom components:

```tsx
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:

```jsx
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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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.