React

Many JupyterLab APIs require Phosphor Widgets which have some additional features over native DOM elements, including:

• Resize events that propagate down the Widget hierarchy.

• Lifecycle events (onBeforeDetach, onAfterAttach, etc.).

• Both CSS-based and absolutely positioned layouts.

We support wrapping React components to turn them into Phosphor widgets using the ReactWidget class from @jupyterlab/apputils:

import * as React from 'react';

import { Widget } from '@phosphor/widgets';
import { ReactWidget } from '@jupyterlab/apputils';

function MyComponent() {
  return <div>My Widget</div>;
}

const myWidget: Widget = ReactWidget.create(<MyComponent />);

Here we use the create static method to transform a React element into a Phosphor widget. Whenever the widget is mounted, the React element will be rendered on the page.

If you need to handle other life cycle events on the Phosphor widget or add other methods to it, you can subbclass ReactWidget and override the render method to return a React element:

import * as React from 'react';

import { Widget } from '@phosphor/widgets';
import { ReactWidget } from '@jupyterlab/apputils';

function MyComponent() {
  return <div>My Widget</div>;
}
class MyWidget extends ReactWidget {
  render() {
    return <MyComponent />;
  }
}
const myWidget: Widget = new MyWidget();

We use Phosphor Signals to represent data that changes over time in JupyterLab. To have your React element change in response to a signal event, use the UseSignal component, which implements the “render props”.

The running component and the createSearchOverlay function in the search overlay use both of these features and serve as a good reference for best practices.

We currently do not have a way of embedding Phosphor widgets inside of React components. If you find yourself trying to do this, we would recommend either converting the Phosphor widget to a React component or using a Phosphor widget for the outer layer component.

We follow the React documentation and “React & Redux in TypeScript - Static Typing Guide” for best practices on using React in TypeScript.