0
# Jupyter Widgets Base
1

2
Jupyter Widgets Base provides the foundational classes, interfaces, and utilities for building interactive widgets in Jupyter environments. This library serves as the core infrastructure that enables the creation of rich, interactive HTML widgets for Jupyter notebooks and IPython kernels.
3

4
## Package Information
5

6
- **Package Name**: @jupyter-widgets/base
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @jupyter-widgets/base`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  WidgetModel, 
16
  DOMWidgetModel, 
17
  WidgetView, 
18
  DOMWidgetView,
19
  IWidgetManager
20
} from "@jupyter-widgets/base";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const { 
27
  WidgetModel, 
28
  DOMWidgetModel, 
29
  WidgetView, 
30
  DOMWidgetView 
31
} = require("@jupyter-widgets/base");
32
```
33

34
## Basic Usage
35

36
```typescript
37
import { WidgetModel, DOMWidgetView, IWidgetManager } from "@jupyter-widgets/base";
38

39
// Create a custom widget model
40
class MyWidgetModel extends WidgetModel {
41
  defaults() {
42
    return {
43
      ...super.defaults(),
44
      _model_name: 'MyWidgetModel',
45
      _view_name: 'MyWidgetView',
46
      value: 0
47
    };
48
  }
49
}
50

51
// Create a custom widget view
52
class MyWidgetView extends DOMWidgetView {
53
  render() {
54
    this.el.innerHTML = `<div>Value: ${this.model.get('value')}</div>`;
55
    
56
    // Listen for model changes
57
    this.listenTo(this.model, 'change:value', this.update);
58
  }
59
  
60
  update() {
61
    this.el.innerHTML = `<div>Value: ${this.model.get('value')}</div>`;
62
  }
63
}
64

65
// Register with widget manager
66
const widgetManager: IWidgetManager = /* get widget manager */;
67
const model = await widgetManager.new_model({
68
  model_name: 'MyWidgetModel',
69
  model_module: 'my-widgets',
70
  model_module_version: '1.0.0'
71
});
72
```
73

74
## Architecture
75

76
Jupyter Widgets Base is built around several key architectural patterns:
77

78
- **Model-View Architecture**: Clean separation between data (models) and presentation (views) using Backbone.js patterns
79
- **Communication Layer**: Bidirectional communication with Jupyter kernels via comm channels
80
- **Layout & Style System**: Flexible CSS-based layout and styling with trait-based property management
81
- **Widget Manager**: Central registry and factory for widget creation and lifecycle management
82
- **Lumino Integration**: Integration with Lumino widgets for advanced UI capabilities
83
- **Type Safety**: Full TypeScript support with comprehensive type definitions
84

85
## Capabilities
86

87
### Core Widget Classes
88

89
Foundation classes for building interactive widgets with model-view separation and kernel communication.
90

91
```typescript { .api }
92
class WidgetModel extends Backbone.Model {
93
  send(content: JSONValue, callbacks?: ICallbacks, buffers?: ArrayBuffer[]): void;
94
  close(comm_closed?: boolean): Promise<void>;
95
  get_state(drop_defaults?: boolean): JSONObject;
96
  save_changes(callbacks?: {}): void;
97
}
98

99
class DOMWidgetModel extends WidgetModel {
100
  static serializers: ISerializers;
101
}
102

103
class WidgetView extends NativeView<WidgetModel> {
104
  render(): any;
105
  update(options?: any): void;
106
  create_child_view<VT>(child_model: WidgetModel, options?: any): Promise<VT>;
107
}
108

109
class DOMWidgetView extends WidgetView {
110
  setLayout(layout: LayoutModel, oldLayout?: LayoutModel): void;
111
  setStyle(style: StyleModel, oldStyle?: StyleModel): void;
112
  update_classes(old_classes: string[], new_classes: string[], el?: HTMLElement): void;
113
}
114
```
115

116
[Core Widget Classes](./widget-classes.md)
117

118
### Native View Foundation
119

120
Enhanced Backbone.View with native DOM event delegation and element manipulation capabilities.
121

122
```typescript { .api }
123
class NativeView<T extends Backbone.Model> extends Backbone.View<T> {
124
  delegate(eventName: string, listener: Function): this;
125
  delegate(eventName: string, selector: string, listener: Function): this;
126
  undelegate(eventName: string, selector?: string, listener?: Function): this;
127
  undelegateEvents(): this;
128
}
129
```
130

131
[Native View Foundation](./nativeview.md)
132

133
### Widget Manager
134

135
Interface and utilities for managing widget lifecycles, creation, and registration within Jupyter environments.
136

137
```typescript { .api }
138
interface IWidgetManager {
139
  get_model(model_id: string): Promise<WidgetModel>;
140
  new_model(options: IModelOptions, serialized_state?: JSONObject): Promise<WidgetModel>;
141
  create_view<VT>(model: WidgetModel, options?: unknown): Promise<VT>;
142
  callbacks(view?: WidgetView): ICallbacks;
143
}
144

145
interface IModelOptions {
146
  model_name: string;
147
  model_module: string;
148
  model_module_version: string;
149
  view_name?: string | null;
150
  view_module?: string | null;
151
  comm?: any;
152
  model_id?: string;
153
}
154
```
155

156
[Widget Manager](./widget-manager.md)
157

158
### Layout & Style System
159

160
CSS-based layout and styling system with trait-based property management for responsive widget positioning and appearance.
161

162
```typescript { .api }
163
class LayoutModel extends WidgetModel {
164
  // Supports CSS properties: width, height, margin, padding, flex, grid, etc.
165
}
166

167
class LayoutView extends WidgetView {
168
  registerTrait(trait: string): void;
169
  handleChange(trait: string, value: any): void;
170
  unlayout(): void;
171
}
172

173
class StyleModel extends WidgetModel {
174
  static styleProperties: { [s: string]: IStyleProperty };
175
}
176

177
class StyleView extends WidgetView {
178
  style(): void;
179
  unstyle(): void;
180
}
181
```
182

183
[Layout & Style System](./layout-style.md)
184

185
### Communication
186

187
Bidirectional communication layer for kernel integration with message handling and comm channel management.
188

189
```typescript { .api }
190
interface IClassicComm {
191
  comm_id: string;
192
  target_name: string;
193
  send(data: JSONValue, callbacks?: ICallbacks, metadata?: JSONObject): string;
194
  open(data: JSONValue, callbacks?: ICallbacks, metadata?: JSONObject): string;
195
  close(data?: JSONValue, callbacks?: ICallbacks, metadata?: JSONObject): string;
196
}
197

198
interface ICallbacks {
199
  shell?: { [key: string]: (msg: KernelMessage.IShellMessage) => void };
200
  iopub?: { [key: string]: (msg: KernelMessage.IOPubMessage) => void };
201
  input?: (msg: KernelMessage.IStdinMessage) => void;
202
}
203
```
204

205
[Communication](./communication.md)
206

207
### Utilities & Helpers
208

209
Utility functions for serialization, buffer handling, view management, and common operations.
210

211
```typescript { .api }
212
function unpack_models(value: any, manager?: IWidgetManager): Promise<WidgetModel | any>;
213
function pack_models(value: any, widget?: WidgetModel): any;
214

215
class ViewList<T> {
216
  constructor(create_view: (model: any, index: any) => T, remove_view: (view: T) => void, context: any);
217
  update(new_models: any[]): Promise<T[]>;
218
  remove(): Promise<void>;
219
}
220

221
function resolvePromisesDict<V>(d: Dict<PromiseLike<V> | V>): Promise<Dict<V>>;
222
function uuid(): string;
223
function isEqual(a: unknown, b: unknown): boolean;
224
```
225

226
[Utilities & Helpers](./utilities.md)
227

228
### Widget Registry
229

230
Registry system for dynamic widget loading and module management.
231

232
```typescript { .api }
233
interface IJupyterWidgetRegistry {
234
  registerWidget(data: IWidgetRegistryData): void;
235
}
236

237
interface IWidgetRegistryData {
238
  name: string;
239
  version: string;
240
  exports: ExportData;
241
}
242

243
type ExportData = ExportMap | Promise<ExportMap> | (() => ExportMap);
244
```
245

246
[Widget Registry](./registry.md)
247

248
### Error Handling
249

250
Error widget components for graceful failure display and debugging support.
251

252
```typescript { .api }
253
function createErrorWidgetModel(error: unknown, msg?: string): typeof WidgetModel;
254

255
class ErrorWidgetView extends DOMWidgetView {
256
  generateErrorMessage(): { msg?: string; stack: string };
257
  render(): void;
258
}
259

260
function createErrorWidgetView(error?: unknown, msg?: string): typeof WidgetView;
261
```
262

263
[Error Handling](./error-handling.md)
264

265
## Version Information
266

267
The package exports version constants for protocol compatibility:
268

269
```typescript { .api }
270
const JUPYTER_WIDGETS_VERSION = '2.0.0';
271
const PROTOCOL_VERSION = '2.1.0';
272
```