0
# Toolbar System
1

2
Flexible toolbar components for both React and Lumino applications with responsive design, command integration, and customizable layouts. The toolbar system supports both traditional Lumino widgets and modern React components.
3

4
## Capabilities
5

6
### Toolbar Base Class
7

8
Basic toolbar widget for organizing and displaying toolbar items.
9

10
```typescript { .api }
11
/**
12
 * Basic toolbar widget for organizing toolbar items
13
 */
14
class Toolbar<T extends Widget = Widget> extends Widget {
15
  /**
16
   * Create a toolbar widget
17
   * @param options - Toolbar configuration options
18
   */
19
  constructor(options?: Toolbar.IOptions);
20
  
21
  /**
22
   * Get iterator of toolbar item names
23
   * @returns Iterator of item names
24
   */
25
  names(): IterableIterator<string>;
26
  
27
  /**
28
   * Add widget to toolbar with given name
29
   * @param name - Unique name for the item
30
   * @param widget - Widget to add
31
   * @returns true if added successfully
32
   */
33
  addItem(name: string, widget: T): boolean;
34
  
35
  /**
36
   * Insert widget at specific index
37
   * @param index - Position to insert at
38
   * @param name - Unique name for the item
39
   * @param widget - Widget to insert
40
   * @returns true if inserted successfully
41
   */
42
  insertItem(index: number, name: string, widget: T): boolean;
43
  
44
  /**
45
   * Insert widget after existing item
46
   * @param at - Name of existing item to insert after
47
   * @param name - Unique name for new item
48
   * @param widget - Widget to insert
49
   * @returns true if inserted successfully
50
   */
51
  insertAfter(at: string, name: string, widget: T): boolean;
52
  
53
  /**
54
   * Insert widget before existing item
55
   * @param at - Name of existing item to insert before
56
   * @param name - Unique name for new item
57
   * @param widget - Widget to insert
58
   * @returns true if inserted successfully
59
   */
60
  insertBefore(at: string, name: string, widget: T): boolean;
61
  
62
  /** Prevent focus when toolbar is clicked */
63
  noFocusOnClick: boolean;
64
}
65

66
namespace Toolbar {
67
  interface IOptions {
68
    /** Custom layout for the toolbar */
69
    layout?: Layout;
70
    /** Prevent focus on click */
71
    noFocusOnClick?: boolean;
72
  }
73
  
74
  interface IWidgetToolbar extends Widget {
75
    /** Optional toolbar property for widgets */
76
    toolbar?: Toolbar;
77
  }
78
  
79
  /**
80
   * Create a spacer item for toolbar layout
81
   * @returns Widget that acts as flexible spacer
82
   */
83
  function createSpacerItem(): Widget;
84
}
85
```
86

87
**Usage Examples:**
88

89
```typescript
90
import { Toolbar, ToolbarButton } from '@jupyterlab/ui-components';
91
import { saveIcon, runIcon, stopIcon } from '@jupyterlab/ui-components';
92

93
// Basic toolbar creation
94
const toolbar = new Toolbar();
95
toolbar.addClass('my-toolbar');
96

97
// Add toolbar buttons
98
const saveButton = new ToolbarButton({
99
  icon: saveIcon,
100
  onClick: () => console.log('Save clicked'),
101
  tooltip: 'Save file'
102
});
103

104
const runButton = new ToolbarButton({
105
  icon: runIcon,
106
  onClick: () => console.log('Run clicked'),
107
  tooltip: 'Run code'
108
});
109

110
// Add items to toolbar
111
toolbar.addItem('save', saveButton);
112
toolbar.addItem('run', runButton);
113

114
// Add spacer for layout
115
const spacer = Toolbar.createSpacerItem();
116
toolbar.addItem('spacer', spacer);
117

118
// Insert item at specific position
119
const stopButton = new ToolbarButton({
120
  icon: stopIcon,
121
  onClick: () => console.log('Stop clicked'),
122
  tooltip: 'Stop execution'
123
});
124
toolbar.insertAfter('run', 'stop', stopButton);
125

126
// Control item visibility and ordering
127
for (const name of toolbar.names()) {
128
  console.log(`Toolbar item: ${name}`);
129
}
130
```
131

132
### ReactiveToolbar
133

134
Enhanced toolbar with responsive design and popup overflow handling.
135

136
```typescript { .api }
137
/**
138
 * Responsive toolbar widget with popup overflow handling
139
 */
140
class ReactiveToolbar extends Toolbar<Widget> {
141
  /**
142
   * Create a reactive toolbar
143
   * @param options - Toolbar configuration options
144
   */
145
  constructor(options?: Toolbar.IOptions);
146
  
147
  /** Popup opener for overflow items */
148
  readonly popupOpener: ToolbarPopupOpener;
149
}
150
```
151

152
**Usage Examples:**
153

154
```typescript
155
import { ReactiveToolbar, ToolbarButton } from '@jupyterlab/ui-components';
156

157
// Create responsive toolbar
158
const responsiveToolbar = new ReactiveToolbar();
159
responsiveToolbar.addClass('responsive-toolbar');
160

161
// Add many items - overflow items will be moved to popup
162
const actions = [
163
  { name: 'new', icon: addIcon, tooltip: 'New file' },
164
  { name: 'open', icon: fileIcon, tooltip: 'Open file' },
165
  { name: 'save', icon: saveIcon, tooltip: 'Save file' },
166
  { name: 'cut', icon: cutIcon, tooltip: 'Cut' },
167
  { name: 'copy', icon: copyIcon, tooltip: 'Copy' },
168
  { name: 'paste', icon: pasteIcon, tooltip: 'Paste' },
169
  { name: 'undo', icon: undoIcon, tooltip: 'Undo' },
170
  { name: 'redo', icon: redoIcon, tooltip: 'Redo' }
171
];
172

173
actions.forEach(action => {
174
  const button = new ToolbarButton({
175
    icon: action.icon,
176
    tooltip: action.tooltip,
177
    onClick: () => console.log(`${action.name} clicked`)
178
  });
179
  responsiveToolbar.addItem(action.name, button);
180
});
181

182
// Access popup opener for customization
183
responsiveToolbar.popupOpener.widgetRequested.connect((sender, widget) => {
184
  console.log('Widget moved to popup:', widget);
185
});
186
```
187

188
### ToolbarButton and ToolbarButtonComponent
189

190
Button components designed for toolbar usage with icon and command support.
191

192
```typescript { .api }
193
/**
194
 * React component for toolbar buttons
195
 */
196
namespace ToolbarButtonComponent {
197
  interface IProps {
198
    /** Additional CSS class */
199
    className?: string;
200
    /** Dataset attributes */
201
    dataset?: DOMStringMap;
202
    /** Button label text */
203
    label?: string;
204
    /** Icon to display */
205
    icon?: LabIcon.IMaybeResolvable;
206
    /** Icon CSS class */
207
    iconClass?: string;
208
    /** Icon label for accessibility */
209
    iconLabel?: string;
210
    /** Tooltip text */
211
    tooltip?: string;
212
    /** Click handler */
213
    onClick?: () => void;
214
    /** Whether button is enabled */
215
    enabled?: boolean;
216
    /** Whether button is pressed/active */
217
    pressed?: boolean;
218
    /** Icon to show when pressed */
219
    pressedIcon?: LabIcon.IMaybeResolvable;
220
    /** Tooltip to show when pressed */
221
    pressedTooltip?: string;
222
    /** Tooltip to show when disabled */
223
    disabledTooltip?: string;
224
    /** Prevent focus on click */
225
    noFocusOnClick?: boolean;
226
    /** Translator for internationalization */
227
    translator?: ITranslator;
228
  }
229
}
230

231
/**
232
 * React toolbar button component
233
 * @param props - Button properties
234
 * @returns JSX button element
235
 */
236
function ToolbarButtonComponent(props: ToolbarButtonComponent.IProps): JSX.Element;
237

238
/**
239
 * Lumino widget wrapper for toolbar button
240
 */
241
class ToolbarButton extends ReactWidget {
242
  /**
243
   * Create toolbar button widget
244
   * @param props - Button properties
245
   */
246
  constructor(props?: ToolbarButtonComponent.IProps);
247
  
248
  /** Whether button is pressed */
249
  set pressed(value: boolean);
250
  get pressed(): boolean;
251
  
252
  /** Whether button is enabled */
253
  set enabled(value: boolean);
254
  get enabled(): boolean;
255
  
256
  /** Click handler function */
257
  set onClick(value: () => void);
258
  get onClick(): () => void;
259
}
260

261
/**
262
 * Add toolbar button CSS class to element
263
 * @param w - Widget to add class to
264
 */
265
function addToolbarButtonClass(w: Widget): void;
266
```
267

268
**Usage Examples:**
269

270
```typescript
271
import { 
272
  ToolbarButton, 
273
  ToolbarButtonComponent,
274
  addToolbarButtonClass
275
} from '@jupyterlab/ui-components';
276
import { saveIcon, runIcon } from '@jupyterlab/ui-components';
277

278
// React toolbar button
279
function MyReactToolbar() {
280
  const [isRunning, setIsRunning] = useState(false);
281
  
282
  return (
283
    <div className="react-toolbar">
284
      <ToolbarButtonComponent
285
        icon={saveIcon}
286
        tooltip="Save file"
287
        onClick={() => handleSave()}
288
      />
289
      
290
      <ToolbarButtonComponent
291
        icon={runIcon}
292
        label="Run"
293
        tooltip={isRunning ? "Stop execution" : "Run code"}
294
        pressed={isRunning}
295
        pressedIcon={stopIcon}
296
        onClick={() => setIsRunning(!isRunning)}
297
      />
298
      
299
      <ToolbarButtonComponent
300
        icon={deleteIcon}
301
        tooltip="Delete item"
302
        enabled={false}
303
        disabledTooltip="No item selected"
304
      />
305
    </div>
306
  );
307
}
308

309
// Lumino toolbar button widget
310
const saveButton = new ToolbarButton({
311
  icon: saveIcon,
312
  tooltip: 'Save current file',
313
  onClick: () => {
314
    console.log('Saving file...');
315
    // Perform save operation
316
  }
317
});
318

319
// Toggle button state
320
const toggleButton = new ToolbarButton({
321
  icon: runIcon,
322
  tooltip: 'Toggle feature',
323
  pressed: false
324
});
325

326
toggleButton.onClick = () => {
327
  toggleButton.pressed = !toggleButton.pressed;
328
  console.log('Feature toggled:', toggleButton.pressed);
329
};
330

331
// Disable/enable button
332
function setButtonEnabled(enabled: boolean) {
333
  saveButton.enabled = enabled;
334
}
335

336
// Add styling
337
addToolbarButtonClass(saveButton);
338
```
339

340
### CommandToolbarButton
341

342
Toolbar button that integrates with Lumino's command system.
343

344
```typescript { .api }
345
/**
346
 * React component for command-based toolbar buttons
347
 */
348
namespace CommandToolbarButtonComponent {
349
  interface IProps {
350
    /** Command registry instance */
351
    commands: CommandRegistry;
352
    /** Command ID to execute */
353
    id: string;
354
    /** Arguments to pass to command */
355
    args?: ReadonlyJSONObject;
356
    /** Override icon from command */
357
    icon?: LabIcon;
358
    /** Override label from command */
359
    label?: string | CommandRegistry.CommandFunc<string>;
360
    /** Override caption from command */
361
    caption?: string;
362
    /** Prevent focus on click */
363
    noFocusOnClick?: boolean;
364
  }
365
}
366

367
/**
368
 * React command toolbar button component
369
 * @param props - Command button properties
370
 * @returns JSX button element
371
 */
372
function CommandToolbarButtonComponent(props: CommandToolbarButtonComponent.IProps): JSX.Element;
373

374
/**
375
 * Lumino widget wrapper for command toolbar button
376
 */
377
class CommandToolbarButton extends ReactWidget {
378
  /**
379
   * Create command toolbar button widget
380
   * @param props - Command button properties
381
   */
382
  constructor(props: CommandToolbarButtonComponent.IProps);
383
  
384
  /** Command ID this button executes */
385
  get commandId(): string;
386
}
387

388
/**
389
 * Add command toolbar button CSS class to element
390
 * @param w - Widget to add class to
391
 */
392
function addCommandToolbarButtonClass(w: Widget): void;
393
```
394

395
**Usage Examples:**
396

397
```typescript
398
import { 
399
  CommandToolbarButton,
400
  CommandToolbarButtonComponent,
401
  addCommandToolbarButtonClass
402
} from '@jupyterlab/ui-components';
403
import { CommandRegistry } from '@lumino/commands';
404
import { saveIcon, runIcon } from '@jupyterlab/ui-components';
405

406
// Set up command registry
407
const commands = new CommandRegistry();
408

409
commands.addCommand('file:save', {
410
  label: 'Save File',
411
  icon: saveIcon,
412
  execute: () => {
413
    console.log('Executing save command');
414
    return saveFile();
415
  }
416
});
417

418
commands.addCommand('code:run', {
419
  label: 'Run Code',
420
  icon: runIcon,
421
  execute: (args) => {
422
    console.log('Running with args:', args);
423
    return runCode(args?.target);
424
  }
425
});
426

427
// React command button
428
function CommandToolbar({ commands }: { commands: CommandRegistry }) {
429
  return (
430
    <div className="command-toolbar">
431
      <CommandToolbarButtonComponent
432
        commands={commands}
433
        id="file:save"
434
      />
435
      
436
      <CommandToolbarButtonComponent
437
        commands={commands}
438
        id="code:run"
439
        args={{ target: 'current-cell' }}
440
        label="Run Cell"
441
      />
442
    </div>
443
  );
444
}
445

446
// Lumino command button widget
447
const saveCommandButton = new CommandToolbarButton({
448
  commands,
449
  id: 'file:save'
450
});
451

452
const runCommandButton = new CommandToolbarButton({
453
  commands,
454
  id: 'code:run',
455
  args: { target: 'all-cells' },
456
  caption: 'Execute all code cells'
457
});
458

459
// Add to toolbar
460
const toolbar = new Toolbar();
461
toolbar.addItem('save-cmd', saveCommandButton);
462
toolbar.addItem('run-cmd', runCommandButton);
463

464
// Add styling
465
addCommandToolbarButtonClass(saveCommandButton);
466
addCommandToolbarButtonClass(runCommandButton);
467

468
// Check command availability
469
if (commands.hasCommand('file:save')) {
470
  console.log('Save command is available');
471
}
472
```
473

474
### Toolbar Layout and Styling
475

476
CSS classes and layout utilities for toolbar customization.
477

478
```typescript { .api }
479
// Toolbar CSS classes are automatically applied
480
// Key classes include:
481

482
// .jp-Toolbar - Main toolbar container
483
// .jp-Toolbar-item - Individual toolbar items  
484
// .jp-Toolbar-spacer - Flexible spacer elements
485
// .jp-ToolbarButton - Standard toolbar buttons
486
// .jp-ToolbarButton-label - Button label text
487
// .jp-mod-disabled - Disabled state modifier
488
// .jp-mod-pressed - Pressed/active state modifier
489
```
490

491
**Usage Examples:**
492

493
```typescript
494
import { Toolbar, ToolbarButton } from '@jupyterlab/ui-components';
495

496
// Custom styled toolbar
497
const styledToolbar = new Toolbar();
498
styledToolbar.addClass('my-custom-toolbar');
499

500
// CSS for custom toolbar styling
501
const customCSS = `
502
.my-custom-toolbar {
503
  background: var(--jp-layout-color2);
504
  border-bottom: 1px solid var(--jp-border-color1);
505
  padding: 4px;
506
}
507

508
.my-custom-toolbar .jp-ToolbarButton {
509
  margin: 0 2px;
510
  border-radius: 3px;
511
}
512

513
.my-custom-toolbar .jp-ToolbarButton:hover {
514
  background: var(--jp-layout-color3);
515
}
516

517
.my-custom-toolbar .jp-Toolbar-spacer {
518
  flex: 1;
519
}
520
`;
521

522
// Apply custom styles
523
const styleSheet = document.createElement('style');
524
styleSheet.textContent = customCSS;
525
document.head.appendChild(styleSheet);
526

527
// Create grouped toolbar sections
528
function createGroupedToolbar() {
529
  const toolbar = new Toolbar();
530
  
531
  // File operations group
532
  const fileButtons = ['new', 'open', 'save'];
533
  fileButtons.forEach(name => {
534
    const button = new ToolbarButton({
535
      icon: getIconForAction(name),
536
      tooltip: `${name} file`
537
    });
538
    button.addClass(`file-action-${name}`);
539
    toolbar.addItem(`file-${name}`, button);
540
  });
541
  
542
  // Add separator spacer
543
  const separator = Toolbar.createSpacerItem();
544
  separator.addClass('toolbar-separator');
545
  toolbar.addItem('separator-1', separator);
546
  
547
  // Edit operations group
548
  const editButtons = ['cut', 'copy', 'paste'];
549
  editButtons.forEach(name => {
550
    const button = new ToolbarButton({
551
      icon: getIconForAction(name),
552
      tooltip: `${name} selection`
553
    });
554
    button.addClass(`edit-action-${name}`);
555
    toolbar.addItem(`edit-${name}`, button);
556
  });
557
  
558
  return toolbar;
559
}
560
```