0
# React Components
1

2
Core React components for building modern JupyterLab interfaces. These components provide consistent styling, full TypeScript support, and integration with the JupyterLab design system.
3

4
## Capabilities
5

6
### Button Component
7

8
Standard button component with JupyterLab styling and multiple variants.
9

10
```typescript { .api }
11
/**
12
 * React button component with JupyterLab styling
13
 * @param props - Button properties extending standard HTML button attributes
14
 * @returns JSX button element
15
 */
16
interface IButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
17
  /** Use minimal styles without background */
18
  minimal?: boolean;
19
  /** Use small size variant */
20
  small?: boolean;
21
}
22

23
function Button(props: IButtonProps): JSX.Element;
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import { Button } from '@jupyterlab/ui-components';
30

31
// Standard button
32
<Button onClick={() => console.log('Clicked')}>
33
  Save File
34
</Button>
35

36
// Minimal style button
37
<Button minimal={true} onClick={() => handleCancel()}>
38
  Cancel
39
</Button>
40

41
// Small button
42
<Button small={true} disabled={false}>
43
  Options
44
</Button>
45

46
// With custom styling
47
<Button 
48
  className="my-custom-button" 
49
  style={{ marginLeft: '10px' }}
50
  type="submit"
51
>
52
  Submit Form
53
</Button>
54
```
55

56
### HTMLSelect Component
57

58
Enhanced HTML select component with icon support and custom styling options.
59

60
```typescript { .api }
61
/**
62
 * HTML select component with enhanced styling and icon support
63
 */
64
interface IOptionProps {
65
  className?: string;
66
  disabled?: boolean;
67
  label?: string;
68
  value: string | number;
69
}
70

71
interface IHTMLSelectProps extends IElementRefProps<HTMLSelectElement>, React.SelectHTMLAttributes<HTMLSelectElement> {
72
  /** Use default JupyterLab styling */
73
  defaultStyle?: boolean;
74
  /** Icon properties for the select */
75
  iconProps?: LabIcon.IProps;
76
  /** Icon to display */
77
  icon?: LabIcon;
78
  /** Array of option values or option objects */
79
  options?: Array<string | number | IOptionProps>;
80
}
81

82
class HTMLSelect extends React.Component<IHTMLSelectProps>;
83

84
const HTML_SELECT_CLASS = 'jp-HTMLSelect';
85
```
86

87
**Usage Examples:**
88

89
```typescript
90
import { HTMLSelect, caretDownIcon } from '@jupyterlab/ui-components';
91

92
// Simple select with string options
93
<HTMLSelect
94
  options={['Python', 'JavaScript', 'R']}
95
  defaultValue="Python"
96
  onChange={(e) => setLanguage(e.target.value)}
97
/>
98

99
// Select with option objects
100
const themeOptions = [
101
  { label: 'Light Theme', value: 'light' },
102
  { label: 'Dark Theme', value: 'dark' },
103
  { label: 'Auto', value: 'auto', disabled: true }
104
];
105

106
<HTMLSelect
107
  options={themeOptions}
108
  icon={caretDownIcon}
109
  defaultStyle={true}
110
  onChange={(e) => setTheme(e.target.value)}
111
/>
112

113
// Custom styled select
114
<HTMLSelect
115
  options={['Small', 'Medium', 'Large']}
116
  className="size-selector"
117
  iconProps={{ className: 'custom-icon' }}
118
/>
119
```
120

121
### InputGroup Component
122

123
Enhanced input component with icon support and integrated styling.
124

125
```typescript { .api }
126
/**
127
 * Input group component with icon support
128
 * @param props - Input properties extending standard HTML input attributes
129
 * @returns JSX input element with optional icon
130
 */
131
interface IInputGroupProps extends React.InputHTMLAttributes<HTMLInputElement> {
132
  /** Reference to the input element */
133
  inputRef?: React.RefObject<HTMLInputElement>;
134
  /** Icon to display on the right side */
135
  rightIcon?: string | LabIcon;
136
}
137

138
function InputGroup(props: IInputGroupProps): JSX.Element;
139
```
140

141
**Usage Examples:**
142

143
```typescript
144
import React, { useRef } from 'react';
145
import { InputGroup, searchIcon, clearIcon } from '@jupyterlab/ui-components';
146

147
// Basic search input
148
<InputGroup
149
  placeholder="Search files..."
150
  rightIcon={searchIcon}
151
  onChange={(e) => setSearchTerm(e.target.value)}
152
/>
153

154
// Input with ref and clear icon
155
const inputRef = useRef<HTMLInputElement>(null);
156

157
<InputGroup
158
  inputRef={inputRef}
159
  rightIcon={clearIcon}
160
  value={inputValue}
161
  onChange={(e) => setInputValue(e.target.value)}
162
  onKeyPress={(e) => {
163
    if (e.key === 'Enter') {
164
      handleSubmit();
165
    }
166
  }}
167
/>
168

169
// Password input with custom styling
170
<InputGroup
171
  type="password"
172
  placeholder="Enter password"
173
  className="password-input"
174
  required={true}
175
/>
176
```
177

178
### FilterBox Component
179

180
Advanced search/filter component with fuzzy search capabilities.
181

182
```typescript { .api }
183
/**
184
 * Filter box component for search and filtering functionality
185
 */
186
interface IScore {
187
  /** Relevance score for the match */
188
  score: number;
189
  /** Array of character indices that matched */
190
  indices: number[] | null;
191
}
192

193
interface IFilterBoxProps {
194
  /** Enable case-sensitive search */
195
  caseSensitive?: boolean;
196
  /** Disable the filter box */
197
  disabled?: boolean;
198
  /** Force refresh of results */
199
  forceRefresh?: boolean;
200
  /** Initial query string */
201
  initialQuery?: string;
202
  /** Reference to input element */
203
  inputRef?: React.RefObject<HTMLInputElement>;
204
  /** Placeholder text */
205
  placeholder?: string;
206
  /** Show search icon */
207
  showIcon?: boolean;
208
  /** Callback to update filter function */
209
  updateFilter: (filterFn: (item: string) => Partial<IScore> | null, query?: string) => void;
210
  /** Enable fuzzy search matching */
211
  useFuzzyFilter?: boolean;
212
  /** Signal for filter settings changes */
213
  filterSettingsChanged?: ISignal<unknown, { [P in keyof IFilterBoxProps]?: IFilterBoxProps[P] }>;
214
}
215

216
function FilterBox(props: IFilterBoxProps): JSX.Element;
217

218
/**
219
 * Factory function to create filename search widget
220
 */
221
function FilenameSearcher(props: IFilterBoxProps): ReactWidget;
222

223
/**
224
 * Widget class for filename searching functionality
225
 * Internal class used by FilenameSearcher factory function
226
 */
227
class FilenameSearcherWidget extends ReactWidget {
228
  constructor(props: IFilterBoxProps);
229
  render(): JSX.Element;
230
}
231

232
/**
233
 * Fuzzy search implementation
234
 * @param source - Text to search in
235
 * @param query - Search query
236
 * @returns Match score and indices, or null if no match
237
 */
238
function fuzzySearch(source: string, query: string): IScore | null;
239

240
/**
241
 * Creates a filter function for use with FilterBox
242
 * @param value - Search query value
243
 * @param useFuzzyFilter - Enable fuzzy matching
244
 * @param caseSensitive - Enable case-sensitive matching
245
 * @returns Filter function that returns match scores
246
 */
247
function updateFilterFunction(
248
  value: string, 
249
  useFuzzyFilter?: boolean, 
250
  caseSensitive?: boolean
251
): (item: string) => Partial<IScore> | null;
252
```
253

254
**Usage Examples:**
255

256
```typescript
257
import React, { useState } from 'react';
258
import { FilterBox, FilenameSearcher, fuzzySearch } from '@jupyterlab/ui-components';
259

260
// File list filter
261
const [filteredFiles, setFilteredFiles] = useState<string[]>([]);
262

263
<FilterBox
264
  placeholder="Filter files..."
265
  useFuzzyFilter={true}
266
  caseSensitive={false}
267
  updateFilter={(filterFn, query) => {
268
    const filtered = fileList.filter(filename => {
269
      const result = filterFn(filename);
270
      return result && result.score && result.score > 0.3;
271
    });
272
    setFilteredFiles(filtered);
273
  }}
274
/>
275

276
// Advanced search with custom scoring
277
<FilterBox
278
  initialQuery="*.ts"
279
  showIcon={true}
280
  updateFilter={(filterFn, query) => {
281
    const results = items.map(item => ({
282
      item,
283
      score: filterFn(item.name)
284
    })).filter(result => result.score?.score > 0.5)
285
      .sort((a, b) => (b.score?.score || 0) - (a.score?.score || 0));
286
    
287
    updateResults(results.map(r => r.item));
288
  }}
289
/>
290

291
// Create a filename search widget (Lumino)
292
const searchWidget = FilenameSearcher({
293
  placeholder: "Search notebooks...",
294
  useFuzzyFilter: true,
295
  updateFilter: (filterFn) => {
296
    // Update notebook list based on filter
297
  }
298
});
299
```
300

301
### Table Component
302

303
Sortable table component with generic type support and custom column rendering.
304

305
```typescript { .api }
306
/**
307
 * Sortable table component with generic data support
308
 */
309
namespace Table {
310
  interface ISortState {
311
    /** Key to sort by */
312
    sortKey?: string | null;
313
    /** Sort direction: 1 for ascending, -1 for descending */
314
    sortDirection: -1 | 1;
315
  }
316
  
317
  interface IRow<T> {
318
    /** Row data */
319
    data: T;
320
    /** Unique row key */
321
    key: string;
322
  }
323
  
324
  interface IColumn<T> {
325
    /** Column identifier */
326
    id: string;
327
    /** Column display label */
328
    label: string;
329
    /** Function to render cell content */
330
    renderCell(data: T): ReactNode;
331
    /** Function to compare values for sorting */
332
    sort(a: T, b: T): number | undefined;
333
    /** Check if column should be available */
334
    isAvailable?(): boolean;
335
    /** Hide this column */
336
    isHidden?: boolean;
337
  }
338
  
339
  interface IOptions<T> extends Partial<ISortState> {
340
    /** Array of table rows */
341
    rows: IRow<T>[];
342
    /** Array of column definitions */
343
    columns: IColumn<T>[];
344
    /** Row click handler */
345
    onRowClick?: React.MouseEventHandler<HTMLTableRowElement>;
346
    /** Component to show when table is empty */
347
    blankIndicator: () => ReactNode;
348
  }
349
}
350

351
function Table<T>(props: Table.IOptions<T>): JSX.Element;
352

353
const TABLE_CLASS = 'jp-sortable-table';
354
```
355

356
**Usage Examples:**
357

358
```typescript
359
import React from 'react';
360
import { Table } from '@jupyterlab/ui-components';
361

362
interface FileData {
363
  name: string;
364
  size: number;
365
  modified: Date;
366
  type: string;
367
}
368

369
// Define table columns
370
const columns: Table.IColumn<FileData>[] = [
371
  {
372
    id: 'name',
373
    label: 'Name',
374
    renderCell: (data) => <strong>{data.name}</strong>,
375
    sort: (a, b) => a.name.localeCompare(b.name)
376
  },
377
  {
378
    id: 'size',
379
    label: 'Size',
380
    renderCell: (data) => `${(data.size / 1024).toFixed(1)} KB`,
381
    sort: (a, b) => a.size - b.size
382
  },
383
  {
384
    id: 'modified',
385
    label: 'Modified',
386
    renderCell: (data) => data.modified.toLocaleDateString(),
387
    sort: (a, b) => a.modified.getTime() - b.modified.getTime()
388
  }
389
];
390

391
// Create table rows
392
const rows: Table.IRow<FileData>[] = files.map(file => ({
393
  key: file.name,
394
  data: file
395
}));
396

397
// Render table
398
<Table
399
  columns={columns}
400
  rows={rows}
401
  sortKey="modified"
402
  sortDirection={-1}
403
  onRowClick={(e) => {
404
    const rowIndex = parseInt(e.currentTarget.dataset.index || '0');
405
    handleFileSelect(files[rowIndex]);
406
  }}
407
  blankIndicator={() => <div>No files found</div>}
408
/>
409
```
410

411
### Form Utilities
412

413
Additional form-related components and utilities.
414

415
```typescript { .api }
416
/**
417
 * Move button for array item reordering
418
 */
419
function MoveButton(props: FormComponent.IButtonProps): JSX.Element;
420

421
/**
422
 * Drop button for removing array items
423
 */
424
function DropButton(props: FormComponent.IButtonProps): JSX.Element;
425

426
/**
427
 * Add button for adding new array items
428
 */
429
function AddButton(props: FormComponent.IButtonProps): JSX.Element;
430

431
/**
432
 * Default UI options for forms
433
 */
434
const DEFAULT_UI_OPTIONS = {
435
  submitButtonOptions: { norender: true }
436
};
437

438
namespace FormComponent {
439
  interface IButtonProps {
440
    /** Button style variant */
441
    buttonStyle?: 'icons' | 'text';
442
    /** Translator for internationalization */
443
    translator?: ITranslator;
444
  }
445
  
446
  interface ILabCustomizerProps extends IButtonProps {
447
    /** Use compact form layout */
448
    compact?: boolean;
449
    /** Show indicators for modified values */
450
    showModifiedFromDefault?: boolean;
451
  }
452
}
453
```
454

455
**Usage Examples:**
456

457
```typescript
458
import { MoveButton, DropButton, AddButton, DEFAULT_UI_OPTIONS } from '@jupyterlab/ui-components';
459

460
// Custom array item controls
461
<div className="array-controls">
462
  <MoveButton buttonStyle="icons" />
463
  <DropButton buttonStyle="text" />
464
  <AddButton buttonStyle="icons" />
465
</div>
466

467
// Form with default UI options
468
const formProps = {
469
  ...otherProps,
470
  uiSchema: {
471
    ...DEFAULT_UI_OPTIONS,
472
    customField: { 'ui:widget': 'select' }
473
  }
474
};
475
```