/docs-sandpack

name: docs-sandpack
description: Use when adding interactive code examples to React docs.

Sandpack Patterns

Quick Start Template

Most examples are single-file. Copy this and modify:

<Sandpack>

` ` `js
import { useState } from 'react';

export default function Example() {
  const [value, setValue] = useState(0);

  return (
    <button onClick={() => setValue(value + 1)}>
      Clicked {value} times
    </button>
  );
}
` ` `

</Sandpack>

---

File Naming

| Pattern | Usage | |---------|-------| | ` ```js ` | Main file (no prefix) | | ` ```js src/FileName.js ` | Supporting files | | ` ```js src/File.js active ` | Active file (reference pages) | | ` ```js src/data.js hidden ` | Hidden files | | ` ```css ` | CSS styles | | ` ```json package.json ` | External dependencies |

**Critical:** Main file must have `export default`.

Line Highlighting

```js {2-4}
function Example() {
  // Lines 2-4
  // will be
  // highlighted
  return null;
}

Code References (numbered callouts)

```js [[1, 4, "age"], [2, 4, "setAge"]]
// Creates numbered markers pointing to "age" and "setAge" on line 4

Expected Errors (intentionally broken examples)

```js {expectedErrors: {'react-compiler': [7]}}
// Line 7 shows as expected error

Multi-File Example

<Sandpack>

```js src/App.js
import Gallery from './Gallery.js';

export default function App() {
  return <Gallery />;
}

export default function Gallery() {
  return <h1>Gallery</h1>;
}

h1 { color: purple; }

</Sandpack>

## External Dependencies

```mdx
<Sandpack>

```js
import { useImmer } from 'use-immer';
// ...

{
  "dependencies": {
    "immer": "1.7.3",
    "use-immer": "0.5.1",
    "react": "latest",
    "react-dom": "latest",
    "react-scripts": "latest"
  }
}

</Sandpack>

## Code Style in Sandpack (Required)

Sandpack examples are held to strict code style standards:

1. **Function declarations** for components (not arrows)
2. **`e`** for event parameters
3. **Single quotes** in JSX
4. **`const`** unless reassignment needed
5. **Spaces in destructuring**: `({ props })` not `({props})`
6. **Two-line createRoot**: separate declaration and render call
7. **Multiline if statements**: always use braces

### Don't Create Hydration Mismatches

Sandpack examples must produce the same output on server and client:

```js
// 🚫 This will cause hydration warnings
export default function App() {
  const isClient = typeof window !== 'undefined';
  return <div>{isClient ? 'Client' : 'Server'}</div>;
}

Use Ref for Non-Rendered State

// 🚫 Don't trigger re-renders for non-visual state
const [mounted, setMounted] = useState(false);
useEffect(() => { setMounted(true); }, []);

// ✅ Use ref instead
const mounted = useRef(false);
useEffect(() => { mounted.current = true; }, []);

forwardRef and memo Patterns

forwardRef - Use Named Function

// ✅ Named function for DevTools display name
const MyInput = forwardRef(function MyInput(props, ref) {
  return <input {...props} ref={ref} />;
});

// 🚫 Anonymous loses name
const MyInput = forwardRef((props, ref) => { ... });

memo - Use Named Function

// ✅ Preserves component name
const Greeting = memo(function Greeting({ name }) {
  return <h1>Hello, {name}</h1>;
});

Line Length

• Prose: ~80 characters
• Code: ~60-70 characters
• Break long lines to avoid horizontal scrolling

Anti-Patterns

| Pattern | Problem | Fix | |---------|---------|-----| | `const Comp = () => {}` | Not standard | `function Comp() {}` | | `onClick={(event) => ...}` | Conflicts with global | `onClick={(e) => ...}` | | `useState` for non-rendered values | Re-renders | Use `useRef` | | Reading `window` during render | Hydration mismatch | Check in useEffect | | Single-line if without braces | Harder to debug | Use multiline with braces | | Chained `createRoot().render()` | Less clear | Two statements | | `//...` without space | Inconsistent | `// ...` with space | | Tabs | Inconsistent | 2 spaces | | `ReactDOM.render` | Deprecated | Use `createRoot` | | Fake package names | Confusing | Use `'./your-storage-layer'` | | `PropsWithChildren` | Outdated | `children?: ReactNode` | | Missing `key` in lists | Warnings | Always include key |

Additional Code Quality Rules

Always Include Keys in Lists

// ✅ Correct
{items.map(item => <li key={item.id}>{item.name}</li>)}

// 🚫 Wrong - missing key
{items.map(item => <li>{item.name}</li>)}

Use Realistic Import Paths

// ✅ Correct - descriptive path
import { fetchData } from './your-data-layer';

// 🚫 Wrong - looks like a real npm package
import { fetchData } from 'cool-data-lib';

Console.log Labels

// ✅ Correct - labeled for clarity
console.log('User:', user);
console.log('Component Stack:', errorInfo.componentStack);

// 🚫 Wrong - unlabeled
console.log(user);

Keep Delays Reasonable

// ✅ Correct - 1-1.5 seconds
setTimeout(() => setLoading(false), 1000);

// 🚫 Wrong - too long, feels sluggish
setTimeout(() => setLoading(false), 3000);

Updating Line Highlights

When modifying code in examples with line highlights (`{2-4}`), **always update the highlight line numbers** to match the new code. Incorrect line numbers cause rendering crashes.

File Name Conventions

• Capitalize file names for component files: `Gallery.js` not `gallery.js`
• After initially explaining files are in `src/`, refer to files by name only: `Gallery.js` not `src/Gallery.js`

Naming Conventions in Code

**Components:** PascalCase

• `Profile`, `Avatar`, `TodoList`, `PackingList`

**State variables:** Destructured pattern

• `const [count, setCount] = useState(0)`
• Booleans: `[isOnline, setIsOnline]`, `[isPacked, setIsPacked]`
• Status strings: `'typing'`, `'submitting'`, `'success'`, `'error'`

**Event handlers:**

• `handleClick`, `handleSubmit`, `handleAddTas