Tutorial Docusaurus React Live

1. Why I added a playground

I wanted readers to learn faster by allowing them to modify examples inline. The @docusaurus/theme-live-codeblock theme integrates react-live to evaluate JSX in real time.

Benefits I gained:

• Instant feedback for readers
• Pedagogical demos without an external sandbox
• Visual consistency with the site
• No page context switching

2. Install the live theme

user@machine: ~/yourproject

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

note

Ensure all @docusaurus/* versions are aligned (e.g. 3.9.1).

3. Configure docusaurus.config.js

Add (or extend) the themes key:

docusaurus.config.js

export default {
	// ...other options
	themes: [
		'@docusaurus/theme-live-codeblock'
	],
};

Optional: adjust styling with custom CSS (Infima is bundled).

4. Create your first jsx live blocks

A MDX fenced block becomes interactive by adding live after the language:

```jsx live
() => <button style={{padding:8}}>Click me</button>
```

You can also write a function:

```jsx live
function Counter(){
	const [n,setN] = React.useState(0);
	return <button onClick={()=>setN(n+1)}>Count: {n}</button>;
}
<Counter />
```

5. Effective patterns

Pattern	Use case	Benefit	Example
Final expression	Tiny demo	Ultra concise	(<Badge>Hi</Badge>)
Const + final identifier	Readable snippet	Shows value	const el=<div/>; el
Function + call	Internal logic	Reusable	function Demo(){...}; <Demo />
Inline hooks	Small interactions	Direct	const [x,setX]=useState(0); <button onClick={()=>setX(x+1)}>{x}
Export default (avoid)	Legacy habit	Noise here	(do not use)

Key rule: the last expression of the block is rendered (no export).

6. Swizzle ReactLiveScope

Problem: inside a live block, your custom components (Tooltip, LogoIcon, etc.) are not known by default.

Solution: create src/theme/ReactLiveScope/index.js to inject a global scope.

import * as React from "react";

// @ts-ignore
import Tooltip from "@site/src/components/Tooltip";
import LogoIcon from "@site/src/components/LogoIcon";
import Skill from "@site/src/components/Skill";
import Contributor from "@site/src/components/Contributor";
import Columns from "@site/src/components/Columns";
import TimeTimer, {
  FallbackBefore,
  FallbackAfter,
} from "@site/src/components/TimeTimer";
import Column from "@site/src/components/Column";
import Card from "@site/src/components/Card";
import CardBody from "@site/src/components/Card/CardBody";
import CardFooter from "@site/src/components/Card/CardFooter";
import CardHeader from "@site/src/components/Card/CardHeader";
import CardImage from "@site/src/components/Card/CardImage";
// Export only the symbols the react-live runtime needs to evaluate snippets.
const {
  useState,
  useEffect,
  useRef,
  useMemo,
  useCallback,
  Fragment,
  forwardRef,
  createElement,
  Children,
} = React;

export default {
  // Keep the complete React object accessible if needed (without spread to avoid 'default' key)
  React,
  // Frequently used hooks in snippets
  useState,
  useEffect,
  useRef,
  useMemo,
  useCallback,
  Fragment,
  forwardRef,
  createElement,
  Children,
  // Custom components exposed in live blocks
  Tooltip,
  LogoIcon,
  Skill,
  Contributor,
  TimeTimer,
  FallbackBefore,
  FallbackAfter,
  Columns,
  Column,
  Card,
  CardBody,
  CardFooter,
  CardHeader,
  CardImage,
  // HTML elements
  center: "center",
};

From there on:

Live Editor

	<Tooltip model="teacher" text="DocuxLab">
		Swizzle ready!
	</Tooltip>

Result

Loading...

7. Advanced examples: interactive Tooltip

Simple model

Live Editor

	<Tooltip text="Simple tooltip">Short content.</Tooltip>

Result

Loading...

Two tooltips side by side

Live Editor

	<div style={{display:'flex', gap:16}}>
		<Tooltip model="teacher" text="Teacher">
			Example with model.
		</Tooltip>
		<Tooltip model="suricate" text="Pépé" position="bottom">
			Bottom position.
		</Tooltip>
	</div>

Result

Loading...

Skill (progress bar)

Live Editor

<div style={{display:'flex', flexDirection:'column', gap:8}}>
	<Skill name={<><LogoIcon name="react" size='24' /> React</>} value={88} type="bar" color="#61DAFB" height={25} />
	<Skill name={<><LogoIcon name="vue" size='24' /> Vue.js</>} value={75} type="bar" color="#4FC08D" height={25} />
	<Skill name={<><LogoIcon name="nodejs" size='24' /> Node.js</>} value={82} type="bar" color="#339933" height={25} />
	<Skill name={<><LogoIcon name="python" size='24' /> Python</>} value={78} type="bar" color="#3776AB" height={25} />
</div>

Result

Loading...

Skill (animated circle)

Live Editor

<div style={{display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(150px, 1fr))', gap: '20px', marginTop: '20px'}}>
  <Skill name={<><LogoIcon name="html-5" size='24' /> </>} value={95} type="circle" color="#E34F26" valuePosition="center" size={100} />
  <Skill name={<><LogoIcon name="css-3" size='24' /> </>} value={90} type="circle" color="#1572B6" valuePosition="center" size={100} />
  <Skill name={<><LogoIcon name="javascript" size='24' /> </>} value={85} type="circle" color="#F7DF1E" valuePosition="center" size={100} />
  </div>

Result

Loading...

Contributor (card)

Live Editor

	<Contributor
		name="Docux"
		github="Juniors017"
		website="https://github.com/Juniors017"
		avatarUrl="/img/docux.webp"
		components={['Tooltip','Skill','etc...']}
		description="Author of several UI components for this site."
        
	/>

Result

Loading...

LogoIcon (variants)

Live Editor

	<div style={{display:'flex',gap:24,alignItems:'center'}}>
		<LogoIcon name="docusaurus" size={40} />
		<LogoIcon name="javascript" size={40} />
		<LogoIcon name="css-3" size={40} />
	</div>

Result

Loading...

8. Best practices

• Keep snippets short and progressive.
• Do not overload the scope (clarity + performance).
• Watch for CSS collisions (avoid heavy globals).
• Prefer an explicit final expression for readability.
• Update @docusaurus/* dependencies together.

9. Quick debugging

Issue	Likely cause	Fix
X is not defined	Component not in scope	Add to ReactLiveScope
Nothing displayed	No final expression	End with JSX or identifier
React import crash	Unnecessary import	Remove import React
Broken style	Infima/custom conflict	Wrap / isolate
Versions mismatch	Misaligned packages	Align versions

10. Going further

Ideas:

• Add a light/dark theme toggle inside demos.
• Persist state (localStorage) in a live block.
• Generate dynamic component variations.

Your turn!