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