0
# Icon System
1

2
Comprehensive SVG-based icon system with 98+ predefined icons, custom icon support, and flexible rendering options for both React and DOM environments. The icon system provides consistent styling, theming support, and optimized rendering.
3

4
## Capabilities
5

6
### LabIcon Class
7

8
Main icon implementation providing SVG rendering and React component generation.
9

10
```typescript { .api }
11
/**
12
 * Main icon implementation for JupyterLab
13
 * Provides SVG rendering and React integration
14
 */
15
class LabIcon implements LabIcon.ILabIcon, VirtualElement.IRenderer {
16
  /**
17
   * Create a new icon
18
   * @param options - Icon configuration options
19
   */
20
  constructor(options: LabIcon.IOptions & { _loading?: boolean });
21
  
22
  /**
23
   * Remove icon from container element
24
   * @param container - Container to remove icon from
25
   * @returns The container element
26
   */
27
  static remove(container: HTMLElement): HTMLElement;
28
  
29
  /**
30
   * Resolve an icon from various sources
31
   * @param icon - Icon to resolve (string name, icon object, or LabIcon instance)
32
   * @returns Resolved LabIcon instance
33
   */
34
  static resolve({ icon }: { icon: LabIcon.IResolvable }): LabIcon;
35
  
36
  /**
37
   * Create icon element with properties
38
   * @param props - Icon properties and resolver props
39
   * @returns HTML element containing the icon
40
   */
41
  static resolveElement(props: Partial<LabIcon.IResolverProps> & LabIcon.IProps): HTMLElement;
42
  
43
  /**
44
   * Create React component for icon
45
   * @param props - Icon properties and resolver props
46
   * @returns JSX element for React rendering
47
   */
48
  static resolveReact(props: Partial<LabIcon.IResolverProps> & LabIcon.IReactProps): JSX.Element;
49
  
50
  /**
51
   * Create SVG element from icon data
52
   * @param icon - Icon name and SVG string
53
   * @returns SVG HTML element or null
54
   */
55
  static resolveSvg({ name, svgstr }: LabIcon.IIcon): HTMLElement | null;
56
  
57
  /**
58
   * Toggle debug mode for icon rendering
59
   * @param debug - Enable or disable debug mode
60
   */
61
  static toggleDebug(debug?: boolean): void;
62
  
63
  /** Icon name identifier */
64
  readonly name: string;
65
  
66
  /** React component for this icon */
67
  readonly react: LabIcon.IReact;
68
  
69
  /** SVG string content */
70
  get svgstr(): string;
71
  set svgstr(svgstr: string);
72
  
73
  /**
74
   * Create new icon with bound properties
75
   * @param props - Properties to bind to the icon
76
   * @returns New LabIcon with bound properties
77
   */
78
  bindprops(props?: LabIcon.IProps): LabIcon;
79
  
80
  /**
81
   * Create HTML element for this icon
82
   * @param props - Icon rendering properties
83
   * @returns HTML element containing the icon
84
   */
85
  element(props?: LabIcon.IProps): HTMLElement;
86
  
87
  /**
88
   * Render icon into container element
89
   * @param container - Container to render into
90
   * @param options - Rendering options
91
   */
92
  render(container: HTMLElement, options?: LabIcon.IRendererOptions): void;
93
  
94
  /** Optional unrender method */
95
  unrender?(container: HTMLElement, options?: LabIcon.IRendererOptions): void;
96
}
97

98
namespace LabIcon {
99
  interface IIcon {
100
    /** Unique icon name */
101
    name: string;
102
    /** SVG content string */
103
    svgstr: string;
104
  }
105
  
106
  interface IProps extends LabIconStyle.IProps {
107
    /** Additional CSS class names */
108
    className?: string;
109
    /** Container element for the icon */
110
    container?: HTMLElement;
111
    /** Accessible label for the icon */
112
    label?: string;
113
    /** HTML tag to use ('div' or 'span') */
114
    tag?: 'div' | 'span' | null;
115
    /** Title attribute for the icon */
116
    title?: string;
117
    /** Slot attribute for web components */
118
    slot?: string | null;
119
  }
120
  
121
  /** Types that can be resolved to an icon */
122
  type IResolvable = string | IIcon | LabIcon;
123
  type IMaybeResolvable = IResolvable | VirtualElement.IRenderer | undefined;
124
  
125
  /** React component type for icons */
126
  type IReact = React.ForwardRefExoticComponent<IReactProps>;
127
  type IReactProps = IProps & React.RefAttributes<SVGElement>;
128
}
129
```
130

131
**Usage Examples:**
132

133
```typescript
134
import { LabIcon, addIcon, saveIcon } from '@jupyterlab/ui-components';
135

136
// Create custom icon
137
const myCustomIcon = new LabIcon({
138
  name: 'my-app:custom-icon',
139
  svgstr: `<svg viewBox="0 0 24 24">
140
    <circle cx="12" cy="12" r="10" fill="currentColor"/>
141
  </svg>`
142
});
143

144
// Render icon to DOM element
145
const container = document.createElement('div');
146
addIcon.render(container, { 
147
  className: 'my-icon-class',
148
  title: 'Add new item'
149
});
150

151
// Create icon element directly
152
const iconElement = saveIcon.element({
153
  className: 'save-icon',
154
  label: 'Save file'
155
});
156
document.body.appendChild(iconElement);
157

158
// Use in React component
159
function MyToolbar() {
160
  return (
161
    <div>
162
      <addIcon.react className="toolbar-icon" title="Add" />
163
      <saveIcon.react className="toolbar-icon" title="Save" />
164
      <myCustomIcon.react />
165
    </div>
166
  );
167
}
168

169
// Resolve icon from string or object
170
const resolvedIcon = LabIcon.resolve({ 
171
  icon: 'ui-components:add' 
172
});
173

174
// Create bound icon with default props
175
const styledAddIcon = addIcon.bindprops({
176
  className: 'default-add-icon',
177
  tag: 'span'
178
});
179
```
180

181
### Predefined Icons
182

183
The package includes 98+ predefined icons organized by category.
184

185
```typescript { .api }
186
// Toolbar and action icons
187
const addIcon: LabIcon;
188
const addAboveIcon: LabIcon;
189
const addBelowIcon: LabIcon;
190
const bugIcon: LabIcon;
191
const bugDotIcon: LabIcon;
192
const checkIcon: LabIcon;
193
const clearIcon: LabIcon;
194
const closeIcon: LabIcon;
195
const closeAllIcon: LabIcon;
196
const codeIcon: LabIcon;
197
const codeCheckIcon: LabIcon;
198
const collapseAllIcon: LabIcon;
199
const collapseIcon: LabIcon;
200
const copyIcon: LabIcon;
201
const cutIcon: LabIcon;
202
const deleteIcon: LabIcon;
203
const downloadIcon: LabIcon;
204
const duplicateIcon: LabIcon;
205
const editIcon: LabIcon;
206
const ellipsesIcon: LabIcon;
207
const expandAllIcon: LabIcon;
208
const expandIcon: LabIcon;
209
const fastForwardIcon: LabIcon;
210
const fileUploadIcon: LabIcon;
211
const filterListIcon: LabIcon;
212
const launchIcon: LabIcon;
213
const linkIcon: LabIcon;
214
const moveDownIcon: LabIcon;
215
const moveUpIcon: LabIcon;
216
const newFolderIcon: LabIcon;
217
const numberingIcon: LabIcon;
218
const offlineBoltIcon: LabIcon;
219
const pasteIcon: LabIcon;
220
const redoIcon: LabIcon;
221
const refreshIcon: LabIcon;
222
const runIcon: LabIcon;
223
const saveIcon: LabIcon;
224
const searchIcon: LabIcon;
225
const stopIcon: LabIcon;
226
const tableRowsIcon: LabIcon;
227
const tagIcon: LabIcon;
228
const treeViewIcon: LabIcon;
229
const undoIcon: LabIcon;
230

231
// Navigation and caret icons
232
const caretDownIcon: LabIcon;
233
const caretDownEmptyIcon: LabIcon;
234
const caretDownEmptyThinIcon: LabIcon;
235
const caretLeftIcon: LabIcon;
236
const caretRightIcon: LabIcon;
237
const caretUpIcon: LabIcon;
238
const caretUpEmptyThinIcon: LabIcon;
239

240
// Dock and layout icons
241
const dockBottomIcon: LabIcon;
242
const dockLeftIcon: LabIcon;
243
const dockRightIcon: LabIcon;
244
const dockTopIcon: LabIcon;
245

246
// File type icons
247
const consoleIcon: LabIcon;
248
const fileIcon: LabIcon;
249
const folderIcon: LabIcon;
250
const folderFavoriteIcon: LabIcon;
251
const homeIcon: LabIcon;
252
const html5Icon: LabIcon;
253
const imageIcon: LabIcon;
254
const inspectorIcon: LabIcon;
255
const jsonIcon: LabIcon;
256
const juliaIcon: LabIcon;
257
const keyboardIcon: LabIcon;
258
const launcherIcon: LabIcon;
259
const markdownIcon: LabIcon;
260
const mermaidIcon: LabIcon;
261
const notebookIcon: LabIcon;
262
const pdfIcon: LabIcon;
263
const pythonIcon: LabIcon;
264
const rKernelIcon: LabIcon;
265
const reactIcon: LabIcon;
266
const settingsIcon: LabIcon;
267
const spreadsheetIcon: LabIcon;
268
const textEditorIcon: LabIcon;
269
const vegaIcon: LabIcon;
270
const yamlIcon: LabIcon;
271

272
// Sidebar icons
273
const buildIcon: LabIcon;
274
const extensionIcon: LabIcon;
275
const paletteIcon: LabIcon;
276
const runningIcon: LabIcon;
277
const shareIcon: LabIcon;
278
const tabIcon: LabIcon;
279
const tocIcon: LabIcon;
280
const userIcon: LabIcon;
281
const usersIcon: LabIcon;
282

283
// Status and indicator icons
284
const bellIcon: LabIcon;
285
const kernelIcon: LabIcon;
286
const lineFormIcon: LabIcon;
287
const listIcon: LabIcon;
288
const notTrustedIcon: LabIcon;
289
const terminalIcon: LabIcon;
290
const trustedIcon: LabIcon;
291

292
// Search and filter icons
293
const caseSensitiveIcon: LabIcon;
294
const filterIcon: LabIcon;
295
const filterDotIcon: LabIcon;
296
const regexIcon: LabIcon;
297
const wordIcon: LabIcon;
298

299
// Debugger icons
300
const exceptionsIcon: LabIcon;
301
const openKernelSourceIcon: LabIcon;
302
const pauseIcon: LabIcon;
303
const stepIntoIcon: LabIcon;
304
const stepOutIcon: LabIcon;
305
const stepOverIcon: LabIcon;
306
const variableIcon: LabIcon;
307
const viewBreakpointIcon: LabIcon;
308

309
// General purpose icons
310
const circleIcon: LabIcon;
311
const circleEmptyIcon: LabIcon;
312
const cleaningIcon: LabIcon;
313
const copyrightIcon: LabIcon;
314
const dotsIcon: LabIcon;
315
const errorIcon: LabIcon;
316
const historyIcon: LabIcon;
317
const infoIcon: LabIcon;
318
const jupyterIcon: LabIcon;
319
const jupyterFaviconIcon: LabIcon;
320
const jupyterlabWordmarkIcon: LabIcon;
321
const lockIcon: LabIcon;
322

323
// Special icons
324
const badIcon: LabIcon;    // Error fallback icon
325
const blankIcon: LabIcon;  // Empty/blank icon
326
```
327

328
**Usage Examples:**
329

330
```typescript
331
import { 
332
  addIcon, 
333
  saveIcon, 
334
  runIcon, 
335
  stopIcon,
336
  folderIcon,
337
  notebookIcon,
338
  pythonIcon
339
} from '@jupyterlab/ui-components';
340

341
// Create toolbar with icons
342
function createToolbar() {
343
  const toolbar = document.createElement('div');
344
  toolbar.className = 'toolbar';
345
  
346
  const buttons = [
347
    { icon: addIcon, title: 'Add new' },
348
    { icon: saveIcon, title: 'Save' },
349
    { icon: runIcon, title: 'Run' },
350
    { icon: stopIcon, title: 'Stop' }
351
  ];
352
  
353
  buttons.forEach(({ icon, title }) => {
354
    const button = document.createElement('button');
355
    button.title = title;
356
    icon.render(button);
357
    toolbar.appendChild(button);
358
  });
359
  
360
  return toolbar;
361
}
362

363
// File type indicator
364
function getFileIcon(filename: string): LabIcon {
365
  const ext = filename.split('.').pop()?.toLowerCase();
366
  
367
  switch (ext) {
368
    case 'ipynb': return notebookIcon;
369
    case 'py': return pythonIcon;
370
    case 'md': return markdownIcon;
371
    case 'json': return jsonIcon;
372
    default: return fileIcon;
373
  }
374
}
375

376
// React component with conditional icons
377
function FileListItem({ file }: { file: { name: string, isDir: boolean } }) {
378
  const icon = file.isDir ? folderIcon : getFileIcon(file.name);
379
  
380
  return (
381
    <div className="file-item">
382
      <icon.react className="file-icon" />
383
      <span>{file.name}</span>
384
    </div>
385
  );
386
}
387
```
388

389
### Icon Styling System
390

391
Advanced styling system for customizing icon appearance and behavior.
392

393
```typescript { .api }
394
/**
395
 * Icon styling system with CSS-in-JS support
396
 */
397
namespace LabIconStyle {
398
  interface IProps extends NestedCSSProperties, ISheetOptions {
399
    /** Additional stylesheets to apply */
400
    stylesheet?: ISheetResolvable | ISheetResolvable[];
401
  }
402
  
403
  /** Icon positioning options */
404
  type IPosition = 
405
    | 'center' 
406
    | 'top' 
407
    | 'right' 
408
    | 'bottom' 
409
    | 'left' 
410
    | 'top right' 
411
    | 'bottom right' 
412
    | 'bottom left' 
413
    | 'top left';
414
  
415
  /** Icon size presets */
416
  type ISize = 'small' | 'normal' | 'large' | 'xlarge';
417
  
418
  /** Built-in stylesheet themes */
419
  type IBuiltin = 
420
    | 'breadCrumb'
421
    | 'commandPaletteHeader'
422
    | 'commandPaletteItem'
423
    | 'launcherCard'
424
    | 'launcherSection'
425
    | 'listing'
426
    | 'listingHeaderItem'
427
    | 'mainAreaTab'
428
    | 'menuItem'
429
    | 'runningItem'
430
    | 'select'
431
    | 'settingsEditor'
432
    | 'sideBar'
433
    | 'splash'
434
    | 'statusBar'
435
    | 'toolbarButton';
436
  
437
  /**
438
   * Generate CSS class for styled icon
439
   * @param props - Style properties
440
   * @returns Generated CSS class name
441
   */
442
  function styleClass(props?: IProps): string;
443
}
444
```
445

446
**Usage Examples:**
447

448
```typescript
449
import { LabIconStyle, saveIcon } from '@jupyterlab/ui-components';
450

451
// Create styled icon classes
452
const toolbarIconClass = LabIconStyle.styleClass({
453
  stylesheet: 'toolbarButton',
454
  elementSize: '16px',
455
  color: 'var(--jp-ui-font-color1)'
456
});
457

458
const menuIconClass = LabIconStyle.styleClass({
459
  stylesheet: 'menuItem',
460
  elementSize: '14px',
461
  margin: '0 4px 0 0'
462
});
463

464
// Use styled icons in React
465
function StyledToolbar() {
466
  return (
467
    <div className="toolbar">
468
      <saveIcon.react className={toolbarIconClass} title="Save" />
469
      <button className="menu-button">
470
        <saveIcon.react className={menuIconClass} />
471
        Save File
472
      </button>
473
    </div>
474
  );
475
}
476

477
// Create custom icon styles
478
const customIconStyle = LabIconStyle.styleClass({
479
  color: '#ff6b35',
480
  elementSize: '20px',
481
  cursor: 'pointer',
482
  ':hover': {
483
    color: '#ff8c42'
484
  }
485
});
486

487
// Apply to DOM elements
488
const iconElement = saveIcon.element({
489
  className: customIconStyle,
490
  title: 'Custom styled save'
491
});
492
```
493

494
### Widget Icon Integration
495

496
Integration components for using icons within Lumino widgets and command systems.
497

498
```typescript { .api }
499
/**
500
 * Enhanced context menu with inline SVG icon support
501
 * Extends Lumino's ContextMenu with icon rendering capabilities
502
 */
503
class ContextMenuSvg extends ContextMenu implements IDisposable {
504
  constructor(options: ContextMenu.IOptions);
505
  
506
  /** Menu instance with SVG support */
507
  readonly menu: MenuSvg;
508
  
509
  /** Whether the menu is disposed */
510
  get isDisposed(): boolean;
511
  
512
  /** Signal emitted when menu opens */
513
  get opened(): ISignal<ContextMenu, void>;
514
  
515
  /** Dispose of resources */
516
  dispose(): void;
517
}
518

519
/**
520
 * Enhanced menu with inline SVG icon rendering
521
 * Extends Lumino's Menu with LabIcon integration
522
 */
523
class MenuSvg extends Menu implements IDisposable {
524
  constructor(options: Menu.IOptions);
525
  
526
  /** Whether the menu is disposed */
527
  get isDisposed(): boolean;
528
  
529
  /** Dispose of resources */
530
  dispose(): void;
531
}
532

533
/**
534
 * Enhanced tab bar with inline SVG icon support
535
 * Provides close icons and add button with SVG rendering
536
 */
537
class TabBarSvg<T> extends TabBar<T> {
538
  constructor(options?: TabBar.IOptions<T>);
539
  
540
  /** Global translator for tab bar */
541
  static translator: ITranslator | null;
542
}
543

544
namespace TabBarSvg {
545
  /**
546
   * Custom renderer for tab bar with SVG icons
547
   */
548
  class Renderer extends TabBar.Renderer {
549
    /** Render close icon as SVG element */
550
    renderCloseIcon(data: TabBar.IRenderData<any>): VirtualElement;
551
    
552
    /** Render tab icon with SVG support */
553
    renderIcon(data: TabBar.IRenderData<any>): VirtualElement;
554
  }
555
  
556
  /** Default SVG-enabled renderer instance */
557
  const defaultRenderer: Renderer;
558
}
559

560
/**
561
 * Command palette renderer with SVG icon support
562
 */
563
namespace CommandPaletteSvg {
564
  /**
565
   * Enhanced renderer for command palette with inline SVG icons
566
   */
567
  class Renderer extends CommandPalette.Renderer {
568
    /** Render header with SVG icons */
569
    renderHeader(data: CommandPalette.IHeaderRenderData): VirtualElement;
570
    
571
    /** Render item icon with SVG support */
572
    renderItemIcon(data: CommandPalette.IItemRenderData): VirtualElement;
573
    
574
    /** Create icon class names for items */
575
    createIconClass(data: CommandPalette.IItemRenderData): string;
576
  }
577
}
578
```
579

580
**Usage Examples:**
581

582
```typescript
583
import { 
584
  ContextMenuSvg, 
585
  MenuSvg, 
586
  TabBarSvg, 
587
  CommandPaletteSvg,
588
  addIcon,
589
  saveIcon,
590
  runIcon 
591
} from '@jupyterlab/ui-components';
592
import { CommandRegistry } from '@lumino/commands';
593

594
// Create context menu with SVG icons
595
function createContextMenuWithIcons(commands: CommandRegistry) {
596
  const contextMenu = new ContextMenuSvg({ commands });
597
  
598
  // Add items with icons automatically rendered
599
  contextMenu.addItem({ command: 'file:save' });
600
  contextMenu.addItem({ command: 'edit:copy' });
601
  contextMenu.addItem({ command: 'edit:paste' });
602
  
603
  return contextMenu;
604
}
605

606
// Create menu with SVG icon support
607
function createMenuWithIcons(commands: CommandRegistry) {
608
  const menu = new MenuSvg({ commands });
609
  menu.title.label = 'File';
610
  
611
  // Icons are automatically rendered for command items
612
  menu.addItem({ command: 'file:new' });
613
  menu.addItem({ command: 'file:save' });
614
  menu.addItem({ type: 'separator' });
615
  menu.addItem({ command: 'file:close' });
616
  
617
  return menu;
618
}
619

620
// Create tab bar with SVG icons and add button
621
function createTabBarWithIcons() {
622
  const tabBar = new TabBarSvg<Widget>({
623
    insertBehavior: 'select-tab-if-needed',
624
    removeBehavior: 'select-previous-tab',
625
    allowDeselect: false
626
  });
627
  
628
  // Add button automatically has SVG icon
629
  tabBar.addButtonEnabled = true;
630
  
631
  return tabBar;
632
}
633

634
// Use custom tab bar renderer
635
const customTabBar = new TabBarSvg({
636
  renderer: new TabBarSvg.Renderer()
637
});
638

639
// Create command palette with SVG icons
640
function createCommandPaletteWithIcons(commands: CommandRegistry) {
641
  const palette = new CommandPalette({
642
    commands,
643
    renderer: new CommandPaletteSvg.Renderer()
644
  });
645
  
646
  // Commands with icons will show SVG icons
647
  palette.addItem({ command: 'file:save', category: 'File' });
648
  palette.addItem({ command: 'edit:undo', category: 'Edit' });
649
  palette.addItem({ command: 'kernel:restart', category: 'Kernel' });
650
  
651
  return palette;
652
}
653

654
// Register commands with icons
655
function setupCommandsWithIcons(commands: CommandRegistry) {
656
  commands.addCommand('file:save', {
657
    label: 'Save File',
658
    icon: saveIcon.bindprops({ svgstr: saveIcon.svgstr }),
659
    execute: () => console.log('File saved')
660
  });
661
  
662
  commands.addCommand('notebook:run-cell', {
663
    label: 'Run Cell',
664
    icon: runIcon.bindprops({ svgstr: runIcon.svgstr }),
665
    execute: () => console.log('Cell executed')
666
  });
667
  
668
  commands.addCommand('file:new', {
669
    label: 'New File',
670
    icon: addIcon.bindprops({ svgstr: addIcon.svgstr }),
671
    execute: () => console.log('New file created')
672
  });
673
}
674

675
// Complete application setup with SVG-enabled widgets
676
function setupApplication() {
677
  const commands = new CommandRegistry();
678
  setupCommandsWithIcons(commands);
679
  
680
  // Create main menu with SVG support
681
  const menuBar = new MenuBar();
682
  const fileMenu = createMenuWithIcons(commands);
683
  menuBar.addMenu(fileMenu);
684
  
685
  // Create tab bar with SVG icons
686
  const tabBar = createTabBarWithIcons();
687
  
688
  // Create context menu
689
  const contextMenu = createContextMenuWithIcons(commands);
690
  
691
  // Create command palette
692
  const palette = createCommandPaletteWithIcons(commands);
693
  
694
  return { menuBar, tabBar, contextMenu, palette };
695
}
696

697
// Handle tab bar events with icon widgets
698
const svgTabBar = new TabBarSvg<Widget>();
699

700
svgTabBar.tabCloseRequested.connect((sender, args) => {
701
  console.log('Tab close requested:', args.title.label);
702
  args.title.owner.close();
703
});
704

705
svgTabBar.addRequested.connect((sender, args) => {
706
  console.log('Add button clicked');
707
  // Create new tab/widget
708
});
709

710
// Dispose of widget resources properly
711
function cleanupWidgets() {
712
  contextMenu.dispose();
713
  fileMenu.dispose();
714
  // Other SVG widgets implement IDisposable
715
}
716
```