0
# JupyterLab CodeMirror
1

2
JupyterLab CodeMirror is the default implementation of the JupyterLab code editor interface using CodeMirror 6. It provides a comprehensive editor provider that integrates modern text editing capabilities with JupyterLab's architecture, featuring syntax highlighting for 100+ programming languages, autocomplete functionality, search capabilities, collaborative editing through Y.js integration, customizable themes and styling, ruler extensions for layout guides, and language-specific features.
3

4
## Package Information
5

6
- **Package Name**: @jupyterlab/codemirror
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @jupyterlab/codemirror`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  CodeMirrorEditor, 
16
  CodeMirrorEditorFactory,
17
  EditorExtensionRegistry,
18
  EditorLanguageRegistry,
19
  EditorThemeRegistry
20
} from "@jupyterlab/codemirror";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const { 
27
  CodeMirrorEditor, 
28
  CodeMirrorEditorFactory,
29
  EditorExtensionRegistry,
30
  EditorLanguageRegistry 
31
} = require("@jupyterlab/codemirror");
32
```
33

34
## Basic Usage
35

36
```typescript
37
import { CodeMirrorEditorFactory } from "@jupyterlab/codemirror";
38
import { CodeEditor } from "@jupyterlab/codeeditor";
39

40
// Create editor factory
41
const factory = new CodeMirrorEditorFactory();
42

43
// Create a document editor
44
const model = new CodeEditor.Model();
45
const editor = factory.newDocumentEditor({
46
  model,
47
  host: document.createElement('div')
48
});
49

50
// Set content and configure
51
model.sharedModel.setSource("console.log('Hello, World!');");
52
model.mimeType = "text/javascript";
53

54
// Focus the editor
55
editor.focus();
56
```
57

58
## Architecture
59

60
JupyterLab CodeMirror is built around several key components:
61

62
- **Editor Core**: `CodeMirrorEditor` class implementing the full `CodeEditor.IEditor` interface
63
- **Factory System**: `CodeMirrorEditorFactory` for creating inline and document editors with different configurations
64
- **Extension Registry**: Modular system with 25+ configurable extensions for customizing editor behavior
65
- **Language Support**: Registry supporting 100+ programming languages with syntax highlighting and language-specific features
66
- **Theme System**: CSS variable-based theming with JupyterLab integration and custom theme support
67
- **Search Framework**: Advanced search and replace functionality with regex support and match highlighting
68
- **Collaborative Editing**: Y.js integration for real-time collaborative editing experiences
69
- **Command System**: Custom commands for editor interactions and keyboard shortcuts
70

71
## Capabilities
72

73
### Editor Core
74

75
Main editor implementation providing all text editing functionality including cursor management, selection handling, and text operations.
76

77
```typescript { .api }
78
class CodeMirrorEditor implements CodeEditor.IEditor {
79
  constructor(options: CodeMirrorEditor.IOptions);
80
  
81
  readonly edgeRequested: Signal<this, CodeEditor.EdgeLocation>;
82
  readonly host: HTMLElement;
83
  readonly editor: EditorView;
84
  readonly doc: Text;
85
  readonly model: CodeEditor.IModel;
86
  readonly uuid: string;
87
  readonly lineCount: number;
88
  readonly selectionStyle: CodeEditor.ISelectionStyle;
89
  
90
  focus(): void;
91
  hasFocus(): boolean;
92
  blur(): void;
93
  resizeToFit(): void;
94
  refresh(): void;
95
  addKeydownHandler(handler: CodeEditor.KeydownHandler): IDisposable;
96
  setSize(size: CodeEditor.IDimension | null): void;
97
  
98
  getCursorPosition(): CodeEditor.IPosition;
99
  setCursorPosition(position: CodeEditor.IPosition, options?: object): void;
100
  getSelections(): CodeEditor.ITextSelection[];
101
  setSelections(selections: CodeEditor.IRange[]): void;
102
  
103
  getOption<K extends keyof CodeEditor.IConfig>(option: K): CodeEditor.IConfig[K];
104
  setOption<K extends keyof CodeEditor.IConfig>(option: K, value: CodeEditor.IConfig[K]): void;
105
  setOptions(options: Partial<CodeEditor.IConfig>): void;
106
  
107
  getLine(index: number): string | undefined;
108
  getOffsetAt(position: CodeEditor.IPosition): number;
109
  getPositionAt(offset: number): CodeEditor.IPosition | undefined;
110
  getCoordinateForPosition(position: CodeEditor.IPosition): CodeEditor.ICoordinate;
111
  getPositionForCoordinate(coordinate: CodeEditor.ICoordinate): CodeEditor.IPosition | null;
112
}
113

114
interface CodeMirrorEditor.IOptions extends CodeEditor.IOptions {
115
  extensionsRegistry?: IEditorExtensionRegistry;
116
  languages?: IEditorLanguageRegistry;
117
}
118
```
119

120
[Editor Core](./editor-core.md)
121

122
### Editor Factory
123

124
Factory service for creating CodeMirror editors with different configurations for inline and document use cases.
125

126
```typescript { .api }
127
class CodeMirrorEditorFactory implements IEditorFactoryService {
128
  constructor(options?: IEditorFactoryOptions);
129
  
130
  readonly newInlineEditor: (options: CodeEditor.IOptions) => CodeMirrorEditor;
131
  readonly newDocumentEditor: (options: CodeEditor.IOptions) => CodeMirrorEditor;
132
  
133
  protected readonly extensions: IEditorExtensionRegistry;
134
  protected readonly languages: IEditorLanguageRegistry;
135
  protected readonly translator: ITranslator;
136
  protected readonly inlineCodeMirrorConfig: Record<string, any>;
137
  protected readonly documentCodeMirrorConfig: Record<string, any>;
138
  
139
  protected newEditor(options: CodeEditor.IOptions & IEditorExtensionFactory.IOptions): CodeMirrorEditor;
140
}
141

142
interface IEditorFactoryOptions {
143
  extensions?: IEditorExtensionRegistry;
144
  languages?: IEditorLanguageRegistry;
145
  translator?: ITranslator;
146
}
147
```
148

149
[Editor Factory](./editor-factory.md)
150

151
### Extension System
152

153
Comprehensive extension registry with 25+ configurable extensions for customizing editor behavior and appearance.
154

155
```typescript { .api }
156
class EditorExtensionRegistry implements IEditorExtensionRegistry {
157
  constructor(options?: { themes?: IEditorThemeRegistry; translator?: ITranslator });
158
  
159
  readonly baseConfiguration: Record<string, any>;
160
  readonly defaultConfiguration: Record<string, any>;
161
  readonly settingsSchema: ReadonlyJSONObject;
162
  
163
  addExtension<T>(factory: IEditorExtensionFactory<T>): void;
164
  createNew(options: IEditorExtensionFactory.IOptions & { config?: Record<string, any> }): IExtensionsHandler;
165
}
166

167
class ExtensionsHandler implements IExtensionsHandler {
168
  constructor(options?: IEditorHandlerOptions);
169
  
170
  readonly configChanged: ISignal<this, Record<string, any>>;
171
  readonly disposed: ISignal<this, void>;
172
  readonly isDisposed: boolean;
173
  
174
  dispose(): void;
175
  getOption(option: string): unknown;
176
  hasOption(option: string): boolean;
177
  setOption(option: string, value: unknown): void;
178
  setOptions(options: Record<string, any>): void;
179
  setBaseOptions(options: Record<string, any>): void;
180
  getInitialExtensions(): Extension[];
181
  injectExtension(view: EditorView, extension: Extension): void;
182
  reconfigureExtension<T>(view: EditorView, key: string, value: T): void;
183
  reconfigureExtensions(view: EditorView, configuration: Record<string, any>): void;
184
}
185
```
186

187
[Extension System](./extension-system.md)
188

189
### Language Support
190

191
Language registry supporting 100+ programming languages with syntax highlighting, autocomplete, and language-specific features.
192

193
```typescript { .api }
194
class EditorLanguageRegistry implements IEditorLanguageRegistry {
195
  constructor();
196
  
197
  addLanguage(language: IEditorLanguage): void;
198
  getLanguage(language: string | IEditorLanguage): Promise<IEditorLanguage | null>;
199
  findBest(language: string | IEditorLanguage, fallback?: boolean): IEditorLanguage | null;
200
  findByMIME(mime: string | readonly string[]): IEditorLanguage | null;
201
  findByName(name: string): IEditorLanguage | null;
202
  findByExtension(ext: string | readonly string[]): IEditorLanguage | null;
203
  findByFileName(name: string): IEditorLanguage | null;
204
  getLanguages(): IEditorLanguage[];
205
  highlight(code: string, language: IEditorLanguage | null, el: HTMLElement): Promise<void>;
206
}
207

208
interface IEditorLanguage {
209
  readonly name: string;
210
  readonly displayName?: string;
211
  readonly alias?: readonly string[];
212
  readonly mime: string | readonly string[];
213
  readonly extensions?: readonly string[];
214
  readonly filename?: RegExp;
215
  readonly support?: LanguageSupport;
216
  readonly load?: () => Promise<LanguageSupport>;
217
}
218
```
219

220
[Language Support](./language-support.md)
221

222
### Theme System
223

224
Theme registry with JupyterLab integration supporting custom themes and CSS variable-based styling.
225

226
```typescript { .api }
227
class EditorThemeRegistry implements IEditorThemeRegistry {
228
  constructor();
229
  
230
  readonly themes: IEditorTheme[];
231
  
232
  defaultTheme(): Extension;
233
  addTheme(theme: IEditorTheme): void;
234
  getTheme(name: string): Extension;
235
}
236

237
interface IEditorTheme {
238
  readonly name: string;
239
  readonly displayName?: string;
240
  readonly theme: Extension;
241
}
242

243
const jupyterTheme: Extension;
244
const jupyterEditorTheme: EditorView.theme;
245
const jupyterHighlightStyle: HighlightStyle;
246
```
247

248
[Theme System](./theme-system.md)
249

250
### Search and Replace
251

252
Advanced search provider with regex support, match highlighting, and comprehensive find/replace functionality.
253

254
```typescript { .api }
255
abstract class EditorSearchProvider<T extends CodeEditor.IModel = CodeEditor.IModel> 
256
  implements IBaseSearchProvider {
257
  
258
  readonly currentMatchIndex: number | null;
259
  readonly isActive: boolean;
260
  readonly matchesCount: number;
261
  readonly stateChanged: ISignal<IBaseSearchProvider, void>;
262
  
263
  startQuery(query: RegExp | null, filters?: IFilters): Promise<void>;
264
  endQuery(): Promise<void>;
265
  highlightNext(loop?: boolean, options?: IHighlightAdjacentMatchOptions): Promise<ISearchMatch | undefined>;
266
  highlightPrevious(loop?: boolean, options?: IHighlightAdjacentMatchOptions): Promise<ISearchMatch | undefined>;
267
  replaceCurrentMatch(newText: string, loop?: boolean, options?: IReplaceOptions): Promise<boolean>;
268
  replaceAllMatches(newText: string, options?: IReplaceOptions): Promise<boolean>;
269
}
270

271
class CodeMirrorSearchHighlighter {
272
  constructor(editor: CodeMirrorEditor | null);
273
  
274
  readonly currentIndex: number | null;
275
  matches: ISearchMatch[];
276
  protectSelection: boolean;
277
}
278
```
279

280
[Search and Replace](./search-replace.md)
281

282
### Editor Commands
283

284
Custom command functions for editor interactions, keyboard shortcuts, and special behaviors.
285

286
```typescript { .api }
287
namespace StateCommands {
288
  function indentMoreOrInsertTab(target: CommandTarget): boolean;
289
  function completerOrInsertNewLine(target: CommandTarget): boolean;
290
  function insertBlankLineOnRun(target: CommandTarget): boolean;
291
  function simplifySelectionAndMaybeSwitchToCommandMode(target: CommandTarget): boolean;
292
  function dedentIfNotLaunchingTooltip(target: CommandTarget): boolean;
293
}
294

295
interface CommandTarget {
296
  dom: HTMLElement;
297
  state: EditorState;
298
  dispatch: (transaction: Transaction) => void;
299
}
300
```
301

302
[Editor Commands](./editor-commands.md)
303

304
### Special Extensions
305

306
Specialized extensions for advanced functionality including collaborative editing, rulers, custom styling, and Python highlighting.
307

308
```typescript { .api }
309
// Y.js collaborative editing
310
function ybinding(options: { ytext: Text; undoManager?: UndoManager }): Extension;
311

312
// Ruler display
313
function rulers(positions: number[]): Extension;
314

315
// Custom styling
316
function customTheme(config: CustomTheme): Extension;
317

318
// Python built-in highlighting
319
function pythonBuiltin(langPython: Language): ViewPlugin;
320

321
// IPython math parsing
322
function parseMathIPython(latexParser?: Parser): MarkdownConfig;
323

324
interface CustomTheme {
325
  fontFamily: string | null;
326
  fontSize: number | null;
327
  lineHeight: number | null;
328
}
329
```
330

331
[Special Extensions](./special-extensions.md)
332

333
### MIME Type Service
334

335
Service for resolving MIME types based on file extensions and language metadata.
336

337
```typescript { .api }
338
class CodeMirrorMimeTypeService implements IEditorMimeTypeService {
339
  constructor(languages: IEditorLanguageRegistry);
340
  
341
  getMimeTypeByLanguage(info: nbformat.ILanguageInfoMetadata): string;
342
  getMimeTypeByFilePath(path: string): string;
343
}
344
```
345

346
[MIME Type Service](./mime-type-service.md)
347

348
## Types
349

350
### Core Types
351

352
```typescript { .api }
353
// Extension system
354
interface IConfigurableExtension<T> {
355
  instance(value: T): Extension;
356
  reconfigure(value: T): StateEffect<T> | null;
357
}
358

359
interface IExtensionsHandler extends IDisposable {
360
  readonly configChanged: ISignal<this, Record<string, any>>;
361
  readonly disposed: ISignal<this, void>;
362
  readonly isDisposed: boolean;
363
  
364
  dispose(): void;
365
  getOption(option: string): unknown;
366
  hasOption(option: string): boolean;
367
  setOption(option: string, value: unknown): void;
368
  setOptions(options: Record<string, any>): void;
369
  setBaseOptions(options: Record<string, any>): void;
370
  getInitialExtensions(): Extension[];
371
  injectExtension(view: EditorView, extension: Extension): void;
372
  reconfigureExtension<T>(view: EditorView, key: string, value: T): void;
373
  reconfigureExtensions(view: EditorView, configuration: Record<string, any>): void;
374
}
375

376
interface IEditorExtensionFactory<T = undefined> {
377
  readonly name: string;
378
  readonly factory: (options: IEditorExtensionFactory.IOptions) => IConfigurableExtension<T> | null;
379
  readonly default?: T;
380
  readonly schema?: ReadonlyJSONObject;
381
}
382

383
namespace IEditorExtensionFactory {
384
  export interface IOptions {
385
    inline: boolean;
386
    model: CodeEditor.IModel;
387
  }
388
}
389

390
interface IEditorHandlerOptions {
391
  baseConfiguration?: Record<string, any>;
392
  config?: Record<string, any>;
393
  defaultExtensions?: [string, IConfigurableExtension<any>][];
394
}
395

396
// Custom styles
397
interface CustomTheme {
398
  fontFamily: string | null;
399
  fontSize: number | null;
400
  lineHeight: number | null;
401
}
402

403
// Search types
404
type SearchStartAnchor = 'auto' | 'selection' | 'selection-start' | 'previous-match' | 'start';
405

406
interface IHighlightMatchOptions {
407
  scroll?: boolean;
408
  select?: boolean;
409
}
410

411
interface IHighlightAdjacentMatchOptions extends IHighlightMatchOptions {
412
  from?: SearchStartAnchor;
413
}
414

415
interface IReplaceOptions {
416
  preserveSelections?: boolean;
417
}
418

419
// Y.js types
420
interface ID {
421
  client: number;
422
  clock: number;
423
}
424

425
interface Position {
426
  type: ID | null;
427
  tname: string | null;
428
  item: ID | null;
429
  assoc: number;
430
}
431

432
interface Range {
433
  yanchor: Position;
434
  yhead: Position;
435
}
436
```
437

438
### Dependency Injection Tokens
439

440
```typescript { .api }
441
const IEditorExtensionRegistry: Token<IEditorExtensionRegistry>;
442
const IEditorLanguageRegistry: Token<IEditorLanguageRegistry>;
443
const IEditorThemeRegistry: Token<IEditorThemeRegistry>;
444
```