0
# React CodeMirror
1
2
React CodeMirror is a comprehensive React wrapper for CodeMirror 6, providing a modern, type-safe interface for integrating advanced code editing capabilities into React applications. It offers both a main component and hook-based API with full TypeScript support, extensible theming, and seamless CodeMirror 6 integration.
3
4
## Package Information
5
6
- **Package Name**: @uiw/react-codemirror
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @uiw/react-codemirror`
10
11
## Core Imports
12
13
```typescript
14
import CodeMirror from "@uiw/react-codemirror";
15
import { useCodeMirror } from "@uiw/react-codemirror";
16
```
17
18
For CommonJS:
19
20
```javascript
21
const CodeMirror = require("@uiw/react-codemirror");
22
const { useCodeMirror } = require("@uiw/react-codemirror");
23
```
24
25
## Basic Usage
26
27
```typescript
28
import React from "react";
29
import CodeMirror from "@uiw/react-codemirror";
30
import { javascript } from "@codemirror/lang-javascript";
31
32
function App() {
33
const [value, setValue] = React.useState("console.log('hello world!');");
34
35
const onChange = React.useCallback((val, viewUpdate) => {
36
console.log('val:', val);
37
setValue(val);
38
}, []);
39
40
return (
41
<CodeMirror
42
value={value}
43
height="200px"
44
extensions={[javascript({ jsx: true })]}
45
onChange={onChange}
46
/>
47
);
48
}
49
```
50
51
## Architecture
52
53
React CodeMirror is built around several key components:
54
55
- **Main Component**: `CodeMirror` component providing declarative React interface
56
- **Hook API**: `useCodeMirror` hook for advanced integration and custom containers
57
- **Extension System**: Full CodeMirror 6 extension support with default configurations
58
- **Theme Engine**: Built-in light/dark themes plus custom theme creation
59
- **State Management**: Automatic synchronization between React state and CodeMirror state
60
- **Event System**: Comprehensive event handling for changes, updates, and editor lifecycle
61
62
## Capabilities
63
64
### Main Component
65
66
Primary React component that renders a CodeMirror 6 editor with full configuration support. Handles all common use cases with declarative props.
67
68
```typescript { .api }
69
declare const ReactCodeMirror: React.ForwardRefExoticComponent<
70
ReactCodeMirrorProps & React.RefAttributes<ReactCodeMirrorRef>
71
>;
72
73
export default ReactCodeMirror;
74
75
interface ReactCodeMirrorProps
76
extends Omit<EditorStateConfig, 'doc' | 'extensions'>,
77
Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'placeholder'> {
78
value?: string;
79
height?: string;
80
minHeight?: string;
81
maxHeight?: string;
82
width?: string;
83
minWidth?: string;
84
maxWidth?: string;
85
autoFocus?: boolean;
86
placeholder?: string | HTMLElement;
87
theme?: 'light' | 'dark' | 'none' | Extension;
88
basicSetup?: boolean | BasicSetupOptions;
89
editable?: boolean;
90
readOnly?: boolean;
91
indentWithTab?: boolean;
92
onChange?(value: string, viewUpdate: ViewUpdate): void;
93
onStatistics?(data: Statistics): void;
94
onUpdate?(viewUpdate: ViewUpdate): void;
95
onCreateEditor?(view: EditorView, state: EditorState): void;
96
extensions?: Extension[];
97
root?: ShadowRoot | Document;
98
initialState?: {
99
json: any;
100
fields?: Record<string, StateField<any>>;
101
};
102
}
103
104
interface ReactCodeMirrorRef {
105
editor?: HTMLDivElement | null;
106
state?: EditorState;
107
view?: EditorView;
108
}
109
```
110
111
[Main Component](./main-component.md)
112
113
### Hook API
114
115
Hook-based interface for advanced integration scenarios, custom containers, and direct CodeMirror state management.
116
117
```typescript { .api }
118
function useCodeMirror(props: UseCodeMirror): {
119
state: EditorState | undefined;
120
setState: React.Dispatch<React.SetStateAction<EditorState | undefined>>;
121
view: EditorView | undefined;
122
setView: React.Dispatch<React.SetStateAction<EditorView | undefined>>;
123
container: HTMLDivElement | null | undefined;
124
setContainer: React.Dispatch<React.SetStateAction<HTMLDivElement | null | undefined>>;
125
};
126
127
interface UseCodeMirror extends ReactCodeMirrorProps {
128
container?: HTMLDivElement | null;
129
}
130
```
131
132
[Hook API](./hook-api.md)
133
134
### Extensions and Configuration
135
136
Default extension management and configuration utilities for setting up common CodeMirror features.
137
138
```typescript { .api }
139
function getDefaultExtensions(options?: DefaultExtensionsOptions): Extension[];
140
141
interface DefaultExtensionsOptions {
142
indentWithTab?: boolean;
143
basicSetup?: boolean | BasicSetupOptions;
144
placeholder?: string | HTMLElement;
145
theme?: 'light' | 'dark' | 'none' | Extension;
146
readOnly?: boolean;
147
editable?: boolean;
148
}
149
```
150
151
[Extensions](./extensions.md)
152
153
### Utilities and Statistics
154
155
Utility functions for extracting editor statistics and managing editor state information.
156
157
```typescript { .api }
158
function getStatistics(view: ViewUpdate): Statistics;
159
160
interface Statistics {
161
length: number;
162
lineCount: number;
163
line: Line;
164
lineBreak: string;
165
readOnly: boolean;
166
tabSize: number;
167
selection: EditorSelection;
168
selectionAsSingle: SelectionRange;
169
ranges: readonly SelectionRange[];
170
selectionCode: string;
171
selections: string[];
172
selectedText: boolean;
173
}
174
```
175
176
[Utilities](./utilities.md)
177
178
### Theme System
179
180
Built-in themes and utilities for creating custom themes for the CodeMirror editor.
181
182
```typescript { .api }
183
const defaultLightThemeOption: Extension;
184
```
185
186
[Themes](./themes.md)
187
188
## Types
189
190
Core types used throughout the API. All CodeMirror types are re-exported for convenience:
191
192
```typescript { .api }
193
// Re-exported from @codemirror/state for direct use
194
export {
195
EditorState,
196
EditorStateConfig,
197
Extension,
198
StateField,
199
EditorSelection,
200
SelectionRange,
201
Line
202
} from '@codemirror/state';
203
204
// Re-exported from @codemirror/view for direct use
205
export {
206
EditorView,
207
ViewUpdate
208
} from '@codemirror/view';
209
210
// Re-exported from @uiw/codemirror-extensions-basic-setup
211
export { BasicSetupOptions } from '@uiw/codemirror-extensions-basic-setup';
212
213
// Internal annotation used for external change tracking
214
export const ExternalChange: import('@codemirror/state').AnnotationType<boolean>;
215
```
216
217
**Usage:**
218
219
```typescript
220
// You can import CodeMirror types directly from react-codemirror
221
import { EditorState, EditorView, Extension } from "@uiw/react-codemirror";
222
223
// Instead of importing from the original packages
224
// import { EditorState, EditorView, Extension } from "@codemirror/state";
225
// import { EditorView } from "@codemirror/view";
226
```