0
# JupyterLab RenderMime Interfaces
1
2
JupyterLab RenderMime Interfaces provides TypeScript interfaces for implementing MIME renderer extensions in JupyterLab. These interfaces define standardized contracts for rendering various MIME types (text, images, rich media) within the JupyterLab ecosystem, enabling extension authors to create custom renderers with full integration support.
3
4
## Package Information
5
6
- **Package Name**: @jupyterlab/rendermime-interfaces
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @jupyterlab/rendermime-interfaces`
10
11
## Core Imports
12
13
```typescript
14
import { IRenderMime } from "@jupyterlab/rendermime-interfaces";
15
import type { ReadonlyPartialJSONObject } from "@lumino/coreutils";
16
import { Widget } from "@lumino/widgets";
17
```
18
19
For CommonJS:
20
21
```javascript
22
const { IRenderMime } = require("@jupyterlab/rendermime-interfaces");
23
const { Widget } = require("@lumino/widgets");
24
```
25
26
## Basic Usage
27
28
```typescript
29
import { IRenderMime } from "@jupyterlab/rendermime-interfaces";
30
import { Widget } from "@lumino/widgets";
31
32
// Define a renderer factory
33
class MyRendererFactory implements IRenderMime.IRendererFactory {
34
readonly safe = true;
35
readonly mimeTypes = ["application/my-custom-type"];
36
readonly defaultRank = 100;
37
38
createRenderer(options: IRenderMime.IRendererOptions): IRenderMime.IRenderer {
39
return new MyRenderer(options);
40
}
41
}
42
43
// Create an extension
44
const extension: IRenderMime.IExtension = {
45
id: "my-extension:renderer",
46
rendererFactory: new MyRendererFactory(),
47
rank: 0,
48
dataType: "string"
49
};
50
```
51
52
## Architecture
53
54
The package is organized around the core `IRenderMime` namespace containing several interface groups:
55
56
- **Data Models**: Interfaces for handling MIME data and metadata (`IMimeModel`)
57
- **Renderer System**: Core interfaces for creating and managing renderers (`IRenderer`, `IRendererFactory`)
58
- **Extension System**: Interfaces for integrating renderers into JupyterLab (`IExtension`, `IExtensionModule`)
59
- **Document System**: Interfaces for document widget factories and file type associations
60
- **Utility Services**: Supporting interfaces for sanitization, URL resolution, and typesetting
61
- **Translation System**: Interfaces for internationalization support
62
63
## Capabilities
64
65
### Data Models
66
67
Core interfaces for handling MIME data, metadata, and toolbar components within the JupyterLab rendering system.
68
69
```typescript { .api }
70
interface IMimeModel {
71
readonly trusted: boolean;
72
readonly data: ReadonlyPartialJSONObject;
73
readonly metadata: ReadonlyPartialJSONObject;
74
setData(options: IMimeModel.ISetDataOptions): void;
75
}
76
77
interface IToolbarItem {
78
name: string;
79
widget: Widget;
80
}
81
```
82
83
[Data Models](./data-models.md)
84
85
### Renderer System
86
87
Core rendering interfaces for creating MIME renderers and factories that integrate with JupyterLab's rendering pipeline.
88
89
```typescript { .api }
90
interface IRenderer extends Widget {
91
renderModel(model: IMimeModel): Promise<void>;
92
}
93
94
interface IRendererFactory {
95
readonly safe: boolean;
96
readonly mimeTypes: ReadonlyArray<string>;
97
readonly defaultRank?: number;
98
createRenderer(options: IRendererOptions): IRenderer;
99
}
100
101
interface IRendererOptions {
102
mimeType: string;
103
sanitizer: ISanitizer;
104
resolver: IResolver | null;
105
linkHandler: ILinkHandler | null;
106
latexTypesetter: ILatexTypesetter | null;
107
markdownParser?: IMarkdownParser | null;
108
translator?: ITranslator;
109
}
110
```
111
112
[Renderer System](./renderer-system.md)
113
114
### Extension System
115
116
Interfaces for packaging and registering MIME renderer extensions within the JupyterLab extension system.
117
118
```typescript { .api }
119
interface IExtension {
120
readonly id: string;
121
readonly description?: string;
122
readonly rendererFactory: IRendererFactory;
123
readonly rank?: number;
124
readonly renderTimeout?: number;
125
readonly dataType?: 'string' | 'json';
126
readonly documentWidgetFactoryOptions?: IDocumentWidgetFactoryOptions | ReadonlyArray<IDocumentWidgetFactoryOptions>;
127
readonly fileTypes?: ReadonlyArray<IFileType>;
128
}
129
130
interface IExtensionModule {
131
readonly default: IExtension | ReadonlyArray<IExtension>;
132
}
133
```
134
135
[Extension System](./extension-system.md)
136
137
### Document System
138
139
Interfaces for document widget factories and file type associations that enable full document rendering capabilities.
140
141
```typescript { .api }
142
interface IDocumentWidgetFactoryOptions {
143
readonly name: string;
144
readonly label?: string;
145
readonly modelName?: string;
146
readonly primaryFileType: string;
147
readonly fileTypes: ReadonlyArray<string>;
148
readonly defaultFor?: ReadonlyArray<string>;
149
readonly defaultRendered?: ReadonlyArray<string>;
150
readonly translator?: ITranslator;
151
readonly toolbarFactory?: (widget?: Widget) => IToolbarItem[];
152
}
153
154
interface IFileType {
155
readonly name: string;
156
readonly mimeTypes: ReadonlyArray<string>;
157
readonly extensions: ReadonlyArray<string>;
158
readonly displayName?: string;
159
readonly pattern?: string;
160
readonly icon?: LabIcon.IResolvable;
161
readonly iconClass?: string;
162
readonly iconLabel?: string;
163
readonly fileFormat?: string | null;
164
}
165
```
166
167
[Document System](./document-system.md)
168
169
### Utility Services
170
171
Supporting interfaces for HTML sanitization, URL resolution, LaTeX typesetting, and Markdown parsing.
172
173
```typescript { .api }
174
interface ISanitizer {
175
getAutolink?(): boolean;
176
sanitize(dirty: string, options?: ISanitizerOptions): string;
177
readonly allowNamedProperties?: boolean;
178
}
179
180
interface IResolver {
181
resolveUrl(url: string): Promise<string>;
182
getDownloadUrl(url: string): Promise<string>;
183
isLocal?(url: string, allowRoot?: boolean): boolean;
184
resolvePath?(path: string): Promise<IResolvedLocation | null>;
185
}
186
187
interface ILatexTypesetter {
188
typeset(element: HTMLElement): void;
189
}
190
191
interface IMarkdownParser {
192
render(source: string): Promise<string>;
193
}
194
```
195
196
[Utility Services](./utility-services.md)
197
198
### Icon System
199
200
Interfaces for defining and rendering icons within the JupyterLab interface, supporting both SVG-based and custom renderers.
201
202
```typescript { .api }
203
namespace LabIcon {
204
interface IIcon {
205
readonly name: string;
206
svgstr: string;
207
}
208
209
interface IRenderer {
210
readonly render: (container: HTMLElement, options?: any) => void;
211
readonly unrender?: (container: HTMLElement, options?: any) => void;
212
}
213
214
type IResolvable = string | (IIcon & Partial<IRenderer>);
215
}
216
```
217
218
[Icon System](./icon-system.md)
219
220
### Translation System
221
222
Internationalization interfaces providing gettext-based translation support for JupyterLab extensions.
223
224
```typescript { .api }
225
interface ITranslator {
226
readonly languageCode: string;
227
load(domain: string): TranslationBundle;
228
}
229
230
type TranslationBundle = {
231
__(msgid: string, ...args: any[]): string;
232
_n(msgid: string, msgid_plural: string, n: number, ...args: any[]): string;
233
_p(msgctxt: string, msgid: string, ...args: any[]): string;
234
_np(msgctxt: string, msgid: string, msgid_plural: string, n: number, ...args: any[]): string;
235
gettext(msgid: string, ...args: any[]): string;
236
ngettext(msgid: string, msgid_plural: string, n: number, ...args: any[]): string;
237
pgettext(msgctxt: string, msgid: string, ...args: any[]): string;
238
npgettext(msgctxt: string, msgid: string, msgid_plural: string, n: number, ...args: any[]): string;
239
dcnpgettext(domain: string, msgctxt: string, msgid: string, msgid_plural: string, n: number, ...args: any[]): string;
240
};
241
```
242
243
[Translation System](./translation-system.md)
244
245
## Types
246
247
Core type definitions used across the package interfaces:
248
249
```typescript { .api }
250
// From @lumino/coreutils
251
type ReadonlyPartialJSONObject = Readonly<Partial<Record<string, any>>>;
252
253
// From @lumino/widgets
254
class Widget {
255
// Base widget class from Lumino
256
}
257
```