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