0
# JupyterLab UI Components
1

2
JupyterLab UI Components is a comprehensive React-based UI components library that provides icons, forms, buttons, widgets, and other interface elements for building consistent JupyterLab applications. It combines React components with Lumino widgets to offer both modern React development patterns and compatibility with the JupyterLab widget framework.
3

4
## Package Information
5

6
- **Package Name**: @jupyterlab/ui-components
7
- **Package Type**: npm
8
- **Language**: TypeScript/React
9
- **Version**: 4.4.7
10
- **Installation**: `npm install @jupyterlab/ui-components`
11

12
## Core Imports
13

14
```typescript
15
// Main components and utilities
16
import {
17
  Button,
18
  HTMLSelect,
19
  InputGroup,
20
  Spinner,
21
  Switch,
22
  ReactWidget,
23
  VDomRenderer,
24
  LabIcon,
25
  Toolbar,
26
  FormComponent,
27
  FormRendererRegistry,
28
  HoverBox,
29
  Styling
30
} from '@jupyterlab/ui-components';
31

32
// Icon system and widgets
33
import {
34
  addIcon,
35
  saveIcon,
36
  runIcon,
37
  stopIcon,
38
  refreshIcon,
39
  closeIcon,
40
  ContextMenuSvg,
41
  MenuSvg,
42
  TabBarSvg,
43
  CommandPaletteSvg
44
} from '@jupyterlab/ui-components';
45

46
// Styling utilities and interfaces
47
import { 
48
  classes, 
49
  classesDedupe,
50
  getReactAttrs,
51
  getTreeItemElement,
52
  LabIconStyle,
53
  IElementRefProps,
54
  DEFAULT_STYLE_CLASS
55
} from '@jupyterlab/ui-components';
56

57
// Token interfaces for dependency injection
58
import {
59
  IFormRenderer,
60
  IFormRendererRegistry,
61
  ILabIconManager
62
} from '@jupyterlab/ui-components';
63
```
64

65
For CommonJS:
66

67
```javascript
68
const {
69
  Button,
70
  HTMLSelect,
71
  LabIcon,
72
  ReactWidget,
73
  FormComponent,
74
  FormRendererRegistry,
75
  HoverBox,
76
  Styling,
77
  addIcon,
78
  saveIcon,
79
  ContextMenuSvg,
80
  MenuSvg,
81
  TabBarSvg,
82
  classes,
83
  classesDedupe,
84
  getReactAttrs
85
} = require('@jupyterlab/ui-components');
86
```
87

88
## Basic Usage
89

90
### React Components
91

92
```typescript
93
import React from 'react';
94
import { Button, HTMLSelect, InputGroup, addIcon } from '@jupyterlab/ui-components';
95

96
// Basic button usage
97
function MyToolbar() {
98
  return (
99
    <div>
100
      <Button 
101
        onClick={() => console.log('Clicked!')}
102
        className="my-button"
103
      >
104
        Add Item
105
      </Button>
106
      
107
      <Button 
108
        minimal={true}
109
        small={true}
110
        onClick={() => console.log('Small clicked!')}
111
      >
112
        Cancel
113
      </Button>
114
    </div>
115
  );
116
}
117

118
// Form controls
119
function MyForm() {
120
  return (
121
    <div>
122
      <InputGroup
123
        placeholder="Enter text..."
124
        rightIcon={addIcon}
125
        onChange={(e) => console.log(e.target.value)}
126
      />
127
      
128
      <HTMLSelect
129
        options={['Option 1', 'Option 2', 'Option 3']}
130
        defaultValue="Option 1"
131
        onChange={(e) => console.log(e.target.value)}
132
      />
133
    </div>
134
  );
135
}
136
```
137

138
### Lumino Widgets
139

140
```typescript
141
import { ReactWidget, Spinner, Switch } from '@jupyterlab/ui-components';
142

143
// Create a React-based Lumino widget
144
class MyWidget extends ReactWidget {
145
  constructor() {
146
    super();
147
    this.addClass('my-widget');
148
  }
149

150
  protected render() {
151
    return (
152
      <div>
153
        <h3>My Custom Widget</h3>
154
        <Spinner />
155
      </div>
156
    );
157
  }
158
}
159

160
// Use Switch widget
161
const switchWidget = new Switch();
162
switchWidget.label = 'Enable feature';
163
switchWidget.value = true;
164
switchWidget.valueChanged.connect((sender, args) => {
165
  console.log('Switch toggled:', args.newValue);
166
});
167
```
168

169
### Icon System
170

171
```typescript
172
import { LabIcon, addIcon, saveIcon, ContextMenuSvg } from '@jupyterlab/ui-components';
173

174
// Use predefined icons
175
const toolbar = document.createElement('div');
176
addIcon.render(toolbar);
177

178
// Create custom icon
179
const myIcon = new LabIcon({
180
  name: 'my-app:my-icon',
181
  svgstr: '<svg>...</svg>'
182
});
183

184
// Use icon in React
185
function IconButton() {
186
  return (
187
    <button>
188
      <addIcon.react />
189
      Add Item
190
    </button>
191
  );
192
}
193

194
// Create context menu with SVG icons
195
const contextMenu = new ContextMenuSvg({ commands });
196
contextMenu.addItem({ command: 'file:save' });
197
```
198

199
### Form System and Utilities
200

201
```typescript
202
import { 
203
  FormComponent, 
204
  FormRendererRegistry, 
205
  HoverBox, 
206
  Styling,
207
  classes,
208
  classesDedupe 
209
} from '@jupyterlab/ui-components';
210

211
// Form rendering with registry
212
const registry = new FormRendererRegistry();
213
registry.addRenderer('custom-field', { 
214
  widgetRenderer: MyCustomWidget 
215
});
216

217
// Position tooltip using HoverBox
218
HoverBox.setGeometry({
219
  anchor: buttonRect,
220
  host: document.body,
221
  node: tooltipElement,
222
  maxHeight: 200,
223
  minHeight: 20,
224
  privilege: 'above'
225
});
226

227
// Combine CSS classes efficiently
228
const buttonClass = classes(
229
  'jp-Button',
230
  isActive && 'jp-mod-active',
231
  customClass
232
);
233

234
// Remove duplicates from class list
235
const cleanClass = classesDedupe(
236
  baseClasses,
237
  themeClasses,
238
  stateClasses
239
);
240

241
// Apply JupyterLab styling to form elements
242
Styling.styleNode(formContainer);
243
```
244

245
## Architecture
246

247
JupyterLab UI Components is built around several key architectural patterns:
248

249
- **React Components**: Modern React functional and class components for UI elements
250
- **Lumino Widgets**: Integration with the Lumino widget framework for JupyterLab compatibility
251
- **Icon System**: Comprehensive SVG-based icon system with 98+ predefined icons
252
- **Styling System**: TypeStyle-based CSS-in-JS with built-in themes and utilities
253
- **Form System**: React JSON Schema Form (RJSF) integration for dynamic forms
254
- **Virtual DOM**: Efficient rendering through React and Lumino's virtual DOM systems
255

256
## Capabilities
257

258
### React Components
259

260
Modern React components for common UI patterns, fully typed with TypeScript support and consistent styling.
261

262
```typescript { .api }
263
// Core form controls
264
interface IButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
265
  minimal?: boolean;
266
  small?: boolean;
267
}
268
function Button(props: IButtonProps): JSX.Element;
269

270
interface IInputGroupProps extends React.InputHTMLAttributes<HTMLInputElement> {
271
  inputRef?: React.RefObject<HTMLInputElement>;
272
  rightIcon?: string | LabIcon;
273
}
274
function InputGroup(props: IInputGroupProps): JSX.Element;
275
```
276

277
[React Components](./components.md)
278

279
### Lumino Widgets
280

281
Widget classes that extend Lumino's Widget base class, providing JupyterLab-compatible components with signals and lifecycle management.
282

283
```typescript { .api }
284
// Base widget integration
285
abstract class ReactWidget extends Widget {
286
  static create(element: ReactRenderElement): ReactWidget;
287
  protected abstract render(): ReactRenderElement | null;
288
}
289

290
// Form widgets
291
class Switch extends Widget {
292
  get value(): boolean;
293
  set value(newValue: boolean);
294
  get valueChanged(): ISignal<this, IChangedArgs<boolean, boolean, 'value'>>;
295
}
296
```
297

298
[Lumino Widgets](./widgets.md)
299

300
### Icon System
301

302
Comprehensive icon management system with 98+ predefined icons and support for custom icons.
303

304
```typescript { .api }
305
class LabIcon implements LabIcon.ILabIcon {
306
  constructor(options: LabIcon.IOptions);
307
  
308
  readonly name: string;
309
  readonly react: LabIcon.IReact;
310
  get svgstr(): string;
311
  
312
  element(props?: LabIcon.IProps): HTMLElement;
313
  render(container: HTMLElement, options?: LabIcon.IRendererOptions): void;
314
}
315
```
316

317
[Icon System](./icons.md)
318

319
### Form System
320

321
Advanced form rendering capabilities using React JSON Schema Form with JupyterLab-specific customizations.
322

323
```typescript { .api }
324
interface IFormComponentProps<T = ReadonlyJSONObject> {
325
  formData: T;
326
  onChange: (e: IChangeEvent<T>) => any;
327
  formContext?: unknown;
328
}
329
function FormComponent(props: IFormComponentProps): JSX.Element;
330
```
331

332
[Form System](./forms.md)
333

334
### Toolbar System
335

336
Flexible toolbar components for both React and Lumino applications with responsive design and command integration.
337

338
```typescript { .api }
339
class Toolbar<T extends Widget = Widget> extends Widget {
340
  addItem(name: string, widget: T): boolean;
341
  insertAfter(at: string, name: string, widget: T): boolean;
342
}
343

344
class ReactiveToolbar extends Toolbar<Widget> {
345
  readonly popupOpener: ToolbarPopupOpener;
346
}
347
```
348

349
[Toolbar System](./toolbars.md)
350

351
### Advanced Widgets
352

353
Specialized widgets for complex use cases including windowed lists, collapsible panels, and search interfaces.
354

355
```typescript { .api }
356
class WindowedList<T extends WindowedList.IModel = WindowedList.IModel> extends Widget {
357
  scrollTo(scrollOffset: number): void;
358
  scrollToItem(index: number, align?: WindowedList.ScrollToAlign): Promise<void>;
359
}
360

361
class Collapser<T extends Widget = Widget> extends Widget {
362
  get collapsed(): boolean;
363
  set collapsed(value: boolean);
364
  toggle(): void;
365
}
366
```
367

368
[Advanced Widgets](./advanced-widgets.md)
369

370
### Utilities
371

372
Helper functions and utilities for styling, DOM manipulation, and React integration.
373

374
```typescript { .api }
375
function classes(...classes: (string | false | undefined | null | { [className: string]: any })[]): string;
376
function getReactAttrs(elem: Element, options?: { ignore?: string[] }): { [key: string]: string | null };
377

378
namespace HoverBox {
379
  function setGeometry(options: IOptions): void;
380
}
381
```
382

383
[Utilities](./utilities.md)