0
# Output Area Widget
1
2
The Output Area Widget provides the visual rendering layer for JupyterLab output areas. It handles MIME type rendering, user input, scroll management, and widget lifecycle for displaying notebook execution results.
3
4
## Capabilities
5
6
### Output Area Widget
7
8
Main widget class for rendering output areas with full interaction support.
9
10
```typescript { .api }
11
/**
12
* Output area widget for rendering notebook outputs with user interaction
13
*/
14
class OutputArea extends Widget {
15
/**
16
* Create a new output area widget
17
* @param options - Configuration options for the output area
18
*/
19
constructor(options: OutputArea.IOptions);
20
21
/** Content factory used by the widget for creating child components */
22
readonly contentFactory: OutputArea.IContentFactory;
23
24
/** The data model used by the widget */
25
readonly model: IOutputAreaModel;
26
27
/** The rendermime registry used for rendering different MIME types */
28
readonly rendermime: IRenderMimeRegistry;
29
30
/** Panel layout containing output widgets */
31
get layout(): PanelLayout;
32
33
/** Read-only array of child widgets in the output area */
34
get widgets(): ReadonlyArray<Widget>;
35
36
/** Signal emitted when the number of displayed outputs changes */
37
readonly outputLengthChanged: ISignal<this, number>;
38
39
/** The kernel future associated with the output area for execution */
40
get future(): Kernel.IShellFuture<
41
KernelMessage.IExecuteRequestMsg,
42
KernelMessage.IExecuteReplyMsg
43
>;
44
set future(value: Kernel.IShellFuture<
45
KernelMessage.IExecuteRequestMsg,
46
KernelMessage.IExecuteReplyMsg
47
>);
48
49
/** Signal emitted when an input is requested from the kernel */
50
get inputRequested(): ISignal<OutputArea, IStdin>;
51
52
/** Whether the output area has a pending input request */
53
get pendingInput(): boolean;
54
55
/** Maximum number of outputs to display (Infinity for no limit) */
56
get maxNumberOutputs(): number;
57
set maxNumberOutputs(limit: number);
58
59
/** Signal emitted when user requests toggling output scrolling mode */
60
get toggleScrolling(): ISignal<OutputArea, void>;
61
62
/** Signal emitted during widget initialization */
63
get initialize(): ISignal<OutputArea, void>;
64
65
/** Widget tracker for individual output widgets */
66
get outputTracker(): WidgetTracker<Widget>;
67
68
/**
69
* Dispose of the widget and clean up resources
70
*/
71
dispose(): void;
72
73
/**
74
* Handle changes to the output model
75
* @param sender - The model that changed
76
* @param args - Details about the change
77
*/
78
protected onModelChanged(
79
sender: IOutputAreaModel,
80
args: IOutputAreaModel.ChangedArgs
81
): void;
82
83
/**
84
* Handle state changes in the output model
85
* @param sender - The model whose state changed
86
* @param change - The index that changed, or void for all items
87
*/
88
protected onStateChanged(
89
sender: IOutputAreaModel,
90
change: number | void
91
): void;
92
93
/**
94
* Handle an input request from the kernel
95
* @param msg - The input request message
96
* @param future - The kernel future for the request
97
*/
98
protected onInputRequest(
99
msg: KernelMessage.IInputRequestMsg,
100
future: Kernel.IShellFuture
101
): void;
102
103
/**
104
* Create an output item widget with prompt and content
105
* @param model - The output model to render
106
* @returns Widget for the output item, or null if cannot render
107
*/
108
protected createOutputItem(model: IOutputModel): Widget | null;
109
110
/**
111
* Create a rendered widget for a specific MIME type
112
* @param model - The output model to render
113
* @returns Widget for the rendered content, or null if unsupported
114
*/
115
protected createRenderedMimetype(model: IOutputModel): Widget | null;
116
}
117
```
118
119
**Usage Examples:**
120
121
```typescript
122
import {
123
OutputArea,
124
OutputAreaModel
125
} from "@jupyterlab/outputarea";
126
import { RenderMimeRegistry } from "@jupyterlab/rendermime";
127
128
// Basic output area setup
129
const model = new OutputAreaModel();
130
const rendermime = new RenderMimeRegistry();
131
132
const outputArea = new OutputArea({
133
model,
134
rendermime,
135
maxNumberOutputs: 100
136
});
137
138
// Listen for output length changes
139
outputArea.outputLengthChanged.connect((sender, count) => {
140
console.log(`Output count changed to: ${count}`);
141
});
142
143
// Handle input requests
144
outputArea.inputRequested.connect((sender, stdin) => {
145
console.log("Input requested from kernel");
146
});
147
148
// Add the widget to a panel
149
panel.addWidget(outputArea);
150
151
// Add some output to see it rendered
152
model.add({
153
output_type: "display_data",
154
data: {
155
"text/html": ["<h1>Hello World</h1>"],
156
"text/plain": ["Hello World"]
157
},
158
metadata: {}
159
});
160
```
161
162
### Simplified Output Area
163
164
Streamlined output area without input handling, ideal for read-only displays.
165
166
```typescript { .api }
167
/**
168
* Simplified output area that handles no input requests
169
*/
170
class SimplifiedOutputArea extends OutputArea {
171
/**
172
* Create a simplified output area widget
173
* @param options - Configuration options (same as OutputArea)
174
*/
175
constructor(options: OutputArea.IOptions);
176
177
/**
178
* Handle input requests by doing nothing (no-op implementation)
179
* @param msg - Input request message (ignored)
180
* @param future - Kernel future (ignored)
181
*/
182
protected onInputRequest(
183
msg: KernelMessage.IInputRequestMsg,
184
future: Kernel.IShellFuture
185
): void;
186
187
/**
188
* Create output items without prompts
189
* @param model - Output model to render
190
* @returns Widget without execution count prompt
191
*/
192
protected createOutputItem(model: IOutputModel): Widget | null;
193
}
194
```
195
196
### Input Components
197
198
Components for handling kernel input requests with history and validation.
199
200
```typescript { .api }
201
/**
202
* Interface for standard input widgets
203
*/
204
interface IStdin extends Widget {
205
/** Promise that resolves with the user's input */
206
readonly value: Promise<string>;
207
}
208
209
/**
210
* Standard input widget with history and keyboard navigation
211
*/
212
class Stdin extends Widget implements IStdin {
213
/**
214
* Create a new stdin widget
215
* @param options - Configuration options for the input
216
*/
217
constructor(options: Stdin.IOptions);
218
219
/** Promise resolving to the user's input value */
220
get value(): Promise<string>;
221
222
/**
223
* Handle keyboard events for input navigation and history
224
* @param event - The keyboard event to handle
225
*/
226
handleEvent(event: KeyboardEvent): void;
227
228
/**
229
* Reset the history search state
230
*
231
* #### Notes
232
* This method clears the current search pattern, allowing new history
233
* navigation to start fresh. Called automatically when using regular
234
* arrow key navigation or Escape key.
235
*/
236
protected resetSearch(): void;
237
}
238
239
/**
240
* Options for creating stdin widgets
241
*/
242
interface Stdin.IOptions {
243
/** The prompt text to display */
244
prompt: string;
245
246
/** Whether the input should be treated as a password */
247
password: boolean;
248
249
/** The kernel future for sending the input reply */
250
future: Kernel.IShellFuture;
251
252
/** Parent header from the input request message */
253
parent_header: KernelMessage.IInputReplyMsg['parent_header'];
254
255
/** Optional translator for internationalization */
256
translator?: ITranslator;
257
258
/** Whether to use global or session-specific input history */
259
inputHistoryScope?: 'global' | 'session';
260
261
/** Whether to show placeholder text for input help */
262
showInputPlaceholder?: boolean;
263
}
264
```
265
266
### Output Prompt
267
268
Component for displaying execution count prompts next to outputs.
269
270
```typescript { .api }
271
/**
272
* Interface for output prompt widgets
273
*/
274
interface IOutputPrompt extends Widget {
275
/** The execution count to display in the prompt */
276
executionCount: nbformat.ExecutionCount;
277
}
278
279
/**
280
* Default output prompt implementation showing execution counts
281
*/
282
class OutputPrompt extends Widget implements IOutputPrompt {
283
/**
284
* Create a new output prompt widget
285
*/
286
constructor();
287
288
/** The execution count for this prompt (null for no count) */
289
get executionCount(): nbformat.ExecutionCount;
290
set executionCount(value: nbformat.ExecutionCount);
291
}
292
```
293
294
### Content Factory
295
296
Factory for creating customizable output area components.
297
298
```typescript { .api }
299
/**
300
* Interface for output area content factories
301
*/
302
interface OutputArea.IContentFactory {
303
/**
304
* Create an output prompt widget
305
* @returns New output prompt instance
306
*/
307
createOutputPrompt(): IOutputPrompt;
308
309
/**
310
* Create a stdin widget for input requests
311
* @param options - Options for the stdin widget
312
* @returns New stdin widget instance
313
*/
314
createStdin(options: Stdin.IOptions): IStdin;
315
}
316
317
/**
318
* Default content factory implementation
319
*/
320
class OutputArea.ContentFactory implements OutputArea.IContentFactory {
321
/**
322
* Create the default output prompt
323
* @returns New OutputPrompt instance
324
*/
325
createOutputPrompt(): IOutputPrompt;
326
327
/**
328
* Create the default stdin widget
329
* @param options - Options for the stdin widget
330
* @returns New Stdin instance
331
*/
332
createStdin(options: Stdin.IOptions): IStdin;
333
}
334
335
/**
336
* Default content factory instance used when none is provided
337
*/
338
namespace OutputArea {
339
export const defaultContentFactory: OutputArea.ContentFactory;
340
}
341
```
342
343
## Widget Options and Utilities
344
345
```typescript { .api }
346
/**
347
* Options for creating output area widgets
348
*/
349
interface OutputArea.IOptions {
350
/** The data model for the output area */
351
model: IOutputAreaModel;
352
353
/** Optional content factory for creating child components */
354
contentFactory?: OutputArea.IContentFactory;
355
356
/** The rendermime registry for rendering different MIME types */
357
rendermime: IRenderMimeRegistry;
358
359
/** Maximum number of outputs to display (default: Infinity) */
360
maxNumberOutputs?: number;
361
362
/** Whether to show a prompt overlay for scrolling toggle */
363
promptOverlay?: boolean;
364
365
/** Optional translator for internationalization */
366
translator?: ITranslator;
367
368
/** Whether to use global or session-specific input history */
369
inputHistoryScope?: 'global' | 'session';
370
371
/** Whether to show placeholder text in input widgets */
372
showInputPlaceholder?: boolean;
373
}
374
375
/**
376
* Execute code on an output area widget
377
* @param code - The code to execute
378
* @param output - The output area to display results in
379
* @param sessionContext - The session context for execution
380
* @param metadata - Optional metadata for the execution
381
* @returns Promise resolving to the execution reply
382
*/
383
async function OutputArea.execute(
384
code: string,
385
output: OutputArea,
386
sessionContext: ISessionContext,
387
metadata?: JSONObject
388
): Promise<KernelMessage.IExecuteReplyMsg | undefined>;
389
390
/**
391
* Determine if a MIME type should be rendered in an isolated frame
392
* @param mimeType - The MIME type to check
393
* @param metadata - Output metadata containing isolation preferences
394
* @returns Whether the MIME type should be isolated
395
*/
396
function OutputArea.isIsolated(
397
mimeType: string,
398
metadata: ReadonlyPartialJSONObject
399
): boolean;
400
```
401
402
## Advanced Features
403
404
### Input History
405
406
The stdin widget includes sophisticated input history management:
407
408
- **History Navigation**: Use ↑/↓ arrow keys to navigate through previous inputs
409
- **History Search**: Use Ctrl+↑/↓ to search through history with current input as pattern
410
- **Session Scoping**: History can be scoped globally or per kernel session
411
- **Persistent Storage**: History is maintained across widget instances
412
413
### Output Trimming
414
415
Large outputs are automatically managed:
416
417
- **Configurable Limits**: Set `maxNumberOutputs` to limit displayed items
418
- **Progressive Display**: Shows trimming indicator with option to expand
419
- **Performance Optimization**: Prevents DOM performance issues with large output sets
420
421
### MIME Type Isolation
422
423
Security and rendering isolation:
424
425
- **Sandboxed Rendering**: Dangerous MIME types rendered in isolated iframes
426
- **Metadata Control**: Isolation can be controlled via output metadata
427
- **Automatic Sizing**: Isolated content automatically sizes to fit content
428
429
## Internal Utility Classes
430
431
### IsolatedRenderer
432
433
Wrapper for rendering untrusted content in isolated iframes for security.
434
435
```typescript { .api }
436
/**
437
* Renderer that wraps another renderer in an isolated iframe for security
438
*/
439
class IsolatedRenderer extends Widget implements IRenderMime.IRenderer {
440
/**
441
* Create an isolated renderer wrapping another renderer
442
* @param wrapped - The renderer to wrap in an iframe
443
*/
444
constructor(wrapped: IRenderMime.IRenderer);
445
446
/**
447
* Render a mime model in the isolated iframe
448
* @param model - The mime model to render
449
* @returns Promise resolving when rendering is complete
450
*/
451
renderModel(model: IRenderMime.IMimeModel): Promise<void>;
452
}
453
```
454
455
### OutputPanel
456
457
Specialized panel for output items with context menu focus handling.
458
459
```typescript { .api }
460
/**
461
* Panel widget focused by contextmenu events, used for output items
462
*/
463
class OutputPanel extends Panel {
464
/**
465
* Create a new output panel widget
466
* @param options - Panel construction options
467
*/
468
constructor(options?: Panel.IOptions);
469
}
470
```
471
472
### TrimmedOutputs
473
474
Information widget displayed when output count exceeds maxNumberOutputs.
475
476
```typescript { .api }
477
/**
478
* Widget displaying information about trimmed outputs with expand functionality
479
*/
480
class TrimmedOutputs extends Widget {
481
/**
482
* Create a trimmed outputs information widget
483
* @param maxNumberOutputs - Number of outputs currently displayed
484
* @param onClick - Callback when user clicks to expand outputs
485
*
486
* #### Notes
487
* The widget is disposed after clicking and calling the callback.
488
*/
489
constructor(
490
maxNumberOutputs: number,
491
onClick: (event: MouseEvent) => void
492
);
493
494
/**
495
* Handle DOM events for the widget
496
* @param event - The DOM event to handle
497
*/
498
handleEvent(event: Event): void;
499
}
500
```