or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-widgets.mdcomponents.mdforms.mdicons.mdindex.mdtoolbars.mdutilities.mdwidgets.md
tile.json

tessl/npm-jupyterlab--ui-components

JupyterLab React-based UI components library providing icons, forms, buttons, and widgets for consistent interface development.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@jupyterlab/ui-components@4.4.x

To install, run

npx @tessl/cli install tessl/npm-jupyterlab--ui-components@4.4.0

index.mddocs/

JupyterLab UI Components

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.

Package Information

  • Package Name: @jupyterlab/ui-components
  • Package Type: npm
  • Language: TypeScript/React
  • Version: 4.4.7
  • Installation: npm install @jupyterlab/ui-components

Core Imports

// Main components and utilities
import {
  Button,
  HTMLSelect,
  InputGroup,
  Spinner,
  Switch,
  ReactWidget,
  VDomRenderer,
  LabIcon,
  Toolbar,
  FormComponent,
  FormRendererRegistry,
  HoverBox,
  Styling
} from '@jupyterlab/ui-components';

// Icon system and widgets
import {
  addIcon,
  saveIcon,
  runIcon,
  stopIcon,
  refreshIcon,
  closeIcon,
  ContextMenuSvg,
  MenuSvg,
  TabBarSvg,
  CommandPaletteSvg
} from '@jupyterlab/ui-components';

// Styling utilities and interfaces
import { 
  classes, 
  classesDedupe,
  getReactAttrs,
  getTreeItemElement,
  LabIconStyle,
  IElementRefProps,
  DEFAULT_STYLE_CLASS
} from '@jupyterlab/ui-components';

// Token interfaces for dependency injection
import {
  IFormRenderer,
  IFormRendererRegistry,
  ILabIconManager
} from '@jupyterlab/ui-components';

For CommonJS:

const {
  Button,
  HTMLSelect,
  LabIcon,
  ReactWidget,
  FormComponent,
  FormRendererRegistry,
  HoverBox,
  Styling,
  addIcon,
  saveIcon,
  ContextMenuSvg,
  MenuSvg,
  TabBarSvg,
  classes,
  classesDedupe,
  getReactAttrs
} = require('@jupyterlab/ui-components');

Basic Usage

React Components

import React from 'react';
import { Button, HTMLSelect, InputGroup, addIcon } from '@jupyterlab/ui-components';

// Basic button usage
function MyToolbar() {
  return (
    <div>
      <Button 
        onClick={() => console.log('Clicked!')}
        className="my-button"
      >
        Add Item
      </Button>
      
      <Button 
        minimal={true}
        small={true}
        onClick={() => console.log('Small clicked!')}
      >
        Cancel
      </Button>
    </div>
  );
}

// Form controls
function MyForm() {
  return (
    <div>
      <InputGroup
        placeholder="Enter text..."
        rightIcon={addIcon}
        onChange={(e) => console.log(e.target.value)}
      />
      
      <HTMLSelect
        options={['Option 1', 'Option 2', 'Option 3']}
        defaultValue="Option 1"
        onChange={(e) => console.log(e.target.value)}
      />
    </div>
  );
}

Lumino Widgets

import { ReactWidget, Spinner, Switch } from '@jupyterlab/ui-components';

// Create a React-based Lumino widget
class MyWidget extends ReactWidget {
  constructor() {
    super();
    this.addClass('my-widget');
  }

  protected render() {
    return (
      <div>
        <h3>My Custom Widget</h3>
        <Spinner />
      </div>
    );
  }
}

// Use Switch widget
const switchWidget = new Switch();
switchWidget.label = 'Enable feature';
switchWidget.value = true;
switchWidget.valueChanged.connect((sender, args) => {
  console.log('Switch toggled:', args.newValue);
});

Icon System

import { LabIcon, addIcon, saveIcon, ContextMenuSvg } from '@jupyterlab/ui-components';

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

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

// Use icon in React
function IconButton() {
  return (
    <button>
      <addIcon.react />
      Add Item
    </button>
  );
}

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

Form System and Utilities

import { 
  FormComponent, 
  FormRendererRegistry, 
  HoverBox, 
  Styling,
  classes,
  classesDedupe 
} from '@jupyterlab/ui-components';

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

// Position tooltip using HoverBox
HoverBox.setGeometry({
  anchor: buttonRect,
  host: document.body,
  node: tooltipElement,
  maxHeight: 200,
  minHeight: 20,
  privilege: 'above'
});

// Combine CSS classes efficiently
const buttonClass = classes(
  'jp-Button',
  isActive && 'jp-mod-active',
  customClass
);

// Remove duplicates from class list
const cleanClass = classesDedupe(
  baseClasses,
  themeClasses,
  stateClasses
);

// Apply JupyterLab styling to form elements
Styling.styleNode(formContainer);

Architecture

JupyterLab UI Components is built around several key architectural patterns:

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

Capabilities

React Components

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

// Core form controls
interface IButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  minimal?: boolean;
  small?: boolean;
}
function Button(props: IButtonProps): JSX.Element;

interface IInputGroupProps extends React.InputHTMLAttributes<HTMLInputElement> {
  inputRef?: React.RefObject<HTMLInputElement>;
  rightIcon?: string | LabIcon;
}
function InputGroup(props: IInputGroupProps): JSX.Element;

React Components

Lumino Widgets

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

// Base widget integration
abstract class ReactWidget extends Widget {
  static create(element: ReactRenderElement): ReactWidget;
  protected abstract render(): ReactRenderElement | null;
}

// Form widgets
class Switch extends Widget {
  get value(): boolean;
  set value(newValue: boolean);
  get valueChanged(): ISignal<this, IChangedArgs<boolean, boolean, 'value'>>;
}

Lumino Widgets

Icon System

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

class LabIcon implements LabIcon.ILabIcon {
  constructor(options: LabIcon.IOptions);
  
  readonly name: string;
  readonly react: LabIcon.IReact;
  get svgstr(): string;
  
  element(props?: LabIcon.IProps): HTMLElement;
  render(container: HTMLElement, options?: LabIcon.IRendererOptions): void;
}

Icon System

Form System

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

interface IFormComponentProps<T = ReadonlyJSONObject> {
  formData: T;
  onChange: (e: IChangeEvent<T>) => any;
  formContext?: unknown;
}
function FormComponent(props: IFormComponentProps): JSX.Element;

Form System

Toolbar System

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

class Toolbar<T extends Widget = Widget> extends Widget {
  addItem(name: string, widget: T): boolean;
  insertAfter(at: string, name: string, widget: T): boolean;
}

class ReactiveToolbar extends Toolbar<Widget> {
  readonly popupOpener: ToolbarPopupOpener;
}

Toolbar System

Advanced Widgets

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

class WindowedList<T extends WindowedList.IModel = WindowedList.IModel> extends Widget {
  scrollTo(scrollOffset: number): void;
  scrollToItem(index: number, align?: WindowedList.ScrollToAlign): Promise<void>;
}

class Collapser<T extends Widget = Widget> extends Widget {
  get collapsed(): boolean;
  set collapsed(value: boolean);
  toggle(): void;
}

Advanced Widgets

Utilities

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

function classes(...classes: (string | false | undefined | null | { [className: string]: any })[]): string;
function getReactAttrs(elem: Element, options?: { ignore?: string[] }): { [key: string]: string | null };

namespace HoverBox {
  function setGeometry(options: IOptions): void;
}

Utilities