0
# Live Components
1

2
Core React components that work together to provide a complete live code editing experience. These components use React Context for state management and provide real-time code editing, transformation, and preview functionality.
3

4
## Capabilities
5

6
### LiveProvider
7

8
Main context provider that manages code transformation, execution, and state for all child components. This component handles the core logic of compiling and executing user code in a safe environment.
9

10
```typescript { .api }
11
/**
12
 * Main context provider for live code editing functionality
13
 * @param props - Configuration and child components
14
 */
15
function LiveProvider(props: {
16
  /** Initial code to display and execute */
17
  code?: string;
18
  /** Whether editing is disabled */
19
  disabled?: boolean;
20
  /** Enable TypeScript transformations (default: true) */
21
  enableTypeScript?: boolean;
22
  /** Language for syntax highlighting (default: "tsx") */
23
  language?: string;
24
  /** Whether to use no-inline evaluation mode requiring explicit render() calls */
25
  noInline?: boolean;
26
  /** Variables available in code execution context */
27
  scope?: Record<string, unknown>;
28
  /** Prism syntax highlighting theme */
29
  theme?: typeof themes.nightOwl;
30
  /** Optional code transformation function (sync or async) */
31
  transformCode?(code: string): string | Promise<string>;
32
  /** Child components to render within the provider context */
33
  children: ReactNode;
34
}): JSX.Element;
35
```
36

37
**Usage Examples:**
38

39
```typescript
40
import { LiveProvider, LiveEditor, LivePreview } from "react-live";
41
import { themes, Prism } from "prism-react-renderer";
42

43
// Basic usage
44
function BasicExample() {
45
  return (
46
    <LiveProvider code="<h1>Hello World</h1>">
47
      <LiveEditor />
48
      <LivePreview />
49
    </LiveProvider>
50
  );
51
}
52

53
// With scope and custom theme
54
function AdvancedExample() {
55
  const scope = { 
56
    Button: MyButton, 
57
    utils: { formatDate, formatCurrency } 
58
  };
59
  
60
  const code = `
61
    <div>
62
      <Button onClick={() => alert('Clicked!')}>
63
        Click me
64
      </Button>
65
      <p>{utils.formatDate(new Date())}</p>
66
    </div>
67
  `;
68

69
  return (
70
    <LiveProvider 
71
      code={code} 
72
      scope={scope}
73
      theme={themes.dracula}
74
      enableTypeScript={true}
75
    >
76
      <LiveEditor />
77
      <LivePreview />
78
    </LiveProvider>
79
  );
80
}
81

82
// No-inline mode (requires render() calls)
83
function NoInlineExample() {
84
  const code = `
85
    function Welcome({ name }) {
86
      return <h1>Hello, {name}!</h1>;
87
    }
88
    
89
    render(<Welcome name="React" />);
90
  `;
91

92
  return (
93
    <LiveProvider code={code} noInline={true}>
94
      <LiveEditor />
95
      <LivePreview />
96
    </LiveProvider>
97
  );
98
}
99

100
// With async transformation
101
function TransformExample() {
102
  const transformCode = async (code: string) => {
103
    // Add import statements or other transformations
104
    return `import React from 'react';\n${code}`;
105
  };
106

107
  return (
108
    <LiveProvider code="<div>Transformed!</div>" transformCode={transformCode}>
109
      <LiveEditor />
110
      <LivePreview />
111
    </LiveProvider>
112
  );
113
}
114
```
115

116
### LiveEditor
117

118
Code editor component with syntax highlighting that consumes the LiveProvider context. Provides a rich editing experience with configurable themes and tab behavior.
119

120
```typescript { .api }
121
/**
122
 * Code editor component with syntax highlighting
123
 * @param props - Editor configuration (extends partial EditorProps)
124
 */
125
function LiveEditor(props: Partial<{
126
  className?: string;
127
  code: string;
128
  disabled?: boolean;
129
  language: string;
130
  prism?: typeof Prism;
131
  style?: CSSProperties;
132
  tabMode?: "focus" | "indentation";
133
  theme?: typeof themes.nightOwl;
134
  onChange?(value: string): void;
135
}>): JSX.Element;
136
```
137

138
**Usage Examples:**
139

140
```typescript
141
import { LiveProvider, LiveEditor } from "react-live";
142

143
// Basic usage (inherits from LiveProvider context)
144
<LiveProvider code="<h1>Hello</h1>">
145
  <LiveEditor />
146
</LiveProvider>
147

148
// With custom styling
149
<LiveProvider code="<h1>Hello</h1>">
150
  <LiveEditor 
151
    style={{ 
152
      fontFamily: 'Monaco, monospace',
153
      fontSize: 14,
154
      backgroundColor: '#f5f5f5'
155
    }}
156
    className="my-editor"
157
  />
158
</LiveProvider>
159

160
// With custom tab behavior
161
<LiveProvider code="<h1>Hello</h1>">
162
  <LiveEditor tabMode="focus" />
163
</LiveProvider>
164
```
165

166
### LivePreview
167

168
Preview component that renders the executed code result in a safe environment with error boundaries. Supports custom wrapper components for styling and layout control.
169

170
```typescript { .api }
171
/**
172
 * Preview component that renders executed code results
173
 * @param props - Preview configuration and wrapper component props
174
 */
175
function LivePreview<T extends keyof JSX.IntrinsicElements>(props: {
176
  Component?: T;
177
} & React.ComponentPropsWithoutRef<T>): JSX.Element;
178

179
function LivePreview<T extends React.ElementType>(props: {
180
  Component?: T;
181
} & React.ComponentPropsWithoutRef<T>): JSX.Element;
182
```
183

184
**Usage Examples:**
185

186
```typescript
187
import { LiveProvider, LiveEditor, LivePreview } from "react-live";
188

189
// Basic usage with default div wrapper
190
<LiveProvider code="<h1>Hello World</h1>">
191
  <LiveEditor />
192
  <LivePreview />
193
</LiveProvider>
194

195
// With custom wrapper component
196
<LiveProvider code="<button>Click me</button>">
197
  <LiveEditor />
198
  <LivePreview 
199
    Component="section" 
200
    className="preview-area"
201
    style={{ padding: 20, border: '1px solid #ccc' }}
202
  />
203
</LiveProvider>
204

205
// With custom React component wrapper
206
function PreviewContainer({ children, ...props }) {
207
  return (
208
    <div className="custom-preview" {...props}>
209
      <h3>Preview:</h3>
210
      {children}
211
    </div>
212
  );
213
}
214

215
<LiveProvider code="<p>Custom wrapper example</p>">
216
  <LiveEditor />
217
  <LivePreview 
218
    Component={PreviewContainer}
219
    data-testid="preview"
220
  />
221
</LiveProvider>
222
```
223

224
### LiveError
225

226
Error display component that shows compilation and runtime errors with detailed feedback. Only renders when errors are present in the live editing context.
227

228
```typescript { .api }
229
/**
230
 * Error display component for showing compilation and runtime errors
231
 * @param props - Props passed to underlying pre element
232
 * @returns JSX element when errors exist, null otherwise
233
 */
234
function LiveError<T extends Record<string, unknown>>(props: T): JSX.Element | null;
235
```
236

237
**Usage Examples:**
238

239
```typescript
240
import { LiveProvider, LiveEditor, LivePreview, LiveError } from "react-live";
241

242
// Basic error display
243
<LiveProvider code="<InvalidComponent />">
244
  <LiveEditor />
245
  <LivePreview />
246
  <LiveError />
247
</LiveProvider>
248

249
// With custom styling
250
<LiveProvider code="const broken = <div><span></div>;">
251
  <LiveEditor />
252
  <LivePreview />
253
  <LiveError 
254
    style={{ 
255
      color: 'red', 
256
      background: '#ffe6e6',
257
      padding: 10,
258
      marginTop: 10
259
    }}
260
    className="error-display"
261
  />
262
</LiveProvider>
263

264
// Complete example with error handling
265
function CodePlayground() {
266
  const [code, setCode] = useState('<h1>Hello World</h1>');
267
  
268
  return (
269
    <div className="playground">
270
      <LiveProvider code={code}>
271
        <div className="editor-section">
272
          <LiveEditor />
273
        </div>
274
        <div className="preview-section">
275
          <LivePreview />
276
          <LiveError style={{ color: 'red', marginTop: 10 }} />
277
        </div>
278
      </LiveProvider>
279
    </div>
280
  );
281
}
282
```
283

284
## Error Handling
285

286
All live components include comprehensive error handling:
287

288
- **Compilation Errors**: TypeScript/JSX syntax errors are caught during transformation
289
- **Runtime Errors**: Component rendering errors are caught by error boundaries
290
- **Transformation Errors**: Custom transformCode function errors are handled gracefully
291
- **Scope Errors**: Undefined variables and missing imports are reported clearly
292

293
Common error scenarios:
294

295
```typescript
296
// Syntax errors
297
const syntaxError = '<div><span></div>'; // Mismatched tags
298

299
// Runtime errors
300
const runtimeError = '<button onClick={undefined.foo()}>Click</button>';
301

302
// Scope errors
303
const scopeError = '<CustomComponent />'; // Not in scope
304

305
// TypeScript errors (when enableTypeScript=true)
306
const typeError = 'const num: number = "string";';
307
```