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