Common Extension Points

Most of the component parts of JupyterLab are designed to be extensible, and they provide public APIs that can be requested in extensions via tokens. A list of tokens that extension authors can request is documented in Core Tokens.

This is intended to be a guide for some of JupyterLab’s most commonly-used extension points. However, it is not an exhaustive account of how to extend the application components, and more detailed descriptions of their public APIs may be found in the JupyterLab and Lumino API documentation.

Commands

Perhaps the most common way to add functionality to JupyterLab is via commands. These are lightweight objects that include a function to execute combined with additional metadata, including how they are labeled and when they are to be enabled. The application has a single command registry, keyed by string command IDs, to which you can add your custom commands.

The commands added to the command registry can then be used to populate several of the JupyterLab user interface elements, including menus and the launcher.

Here is a sample block of code that adds a command to the application (given by app):

const commandID = 'my-command';
const toggled = false;

app.commands.addCommand(commandID, {
  label: 'My Cool Command',
  isEnabled: true,
  isVisible: true,
  isToggled: () => toggled,
  iconClass: 'some-css-icon-class',
  execute: () => {
    console.log(`Executed ${commandID}`);
    toggled = !toggled;
});

This example adds a new command, which, when triggered, calls the execute function. isEnabled indicates whether the command is enabled, and determines whether renderings of it are greyed out. isToggled indicates whether to render a check mark next to the command. isVisible indicates whether to render the command at all. iconClass specifies a CSS class which can be used to display an icon next to renderings of the command.

Each of isEnabled, isToggled, and isVisible can be either a boolean value or a function that returns a boolean value, in case you want to do some logic in order to determine those conditions.

Likewise, each of label and iconClass can be either a string value or a function that returns a string value.

There are several more options which can be passed into the command registry when adding new commands. These are documented here.

After a command has been added to the application command registry you can add them to various places in the application user interface, where they will be rendered using the metadata you provided.

Command Palette

In order to add a command to the command palette, you need to request the ICommandPalette token in your extension. Here is an example showing how to add a command to the command palette (given by palette):

palette.addItem({
  command: commandID,
  category: 'my-category'
  args: {}
});

The command ID is the same ID that you used when registering the command. You must also provide a category, which determines the subheading of the command palette in which to render the command. It can be a preexisting category (e.g., 'notebook'), or a new one of your own choosing.

The args are a JSON object that will be passed into your command’s functions at render/execute time. You can use these to customize the behavior of your command depending on how it is invoked. For instance, you can pass in args: { isPalette: true }. Your command label function can then check the args it is provided for isPalette, and return a different label in that case. This can be useful to make a single command flexible enough to work in multiple contexts.

Context Menu

The application context menu is shown when the user right-clicks, and is populated with menu items that are most relevant to the thing that the user clicked.

The context menu system determines which items to show based on CSS selectors. It propagates up the DOM tree and tests whether a given HTML element matches the CSS selector provided by a given command.

Here is an example showing how to add a command to the application context menu:

app.contextMenu.addItem({
  command: commandID,
  selector: '.jp-Notebook'
})

In this example, the command indicated by commandID is shown whenever the user right-clicks on a DOM element matching .jp-Notebook (that is to say, a notebook). The selector can be any valid CSS selector, and may target your own UI elements, or existing ones. A list of CSS selectors currently used by context menu commands is given in Commonly used CSS selectors.

Keyboard Shortcuts

There are two ways of adding keyboard shortcuts in JupyterLab. If you don’t want the shortcuts to be user-configurable, you can add them directly to the application command registry:

app.commands.addKeyBinding({
  command: commandID,
  args: {},
  keys: ['Accel T'],
  selector: '.jp-Notebook'
});

In this example my-command command is mapped to Accel T, where Accel corresponds to Cmd on a Mac and Ctrl on Windows and Linux computers.

The behavior for keyboard shortcuts is very similar to that of the context menu: the shortcut handler propagates up the DOM tree from the focused element and tests each element against the registered selectors. If a match is found, then that command is executed with the provided args. Full documentation for the options for addKeyBinding can be found here.

JupyterLab also provides integration with its settings system for keyboard shortcuts. Your extension can provide a settings schema with a jupyter.lab.shortcuts key, declaring default keyboard shortcuts for a command:

{
  "jupyter.lab.shortcuts": [
    {
      "command": "my-command",
      "keys": ["Accel T"],
      "selector": ".jp-mod-searchable"
    }
  ]
}

Shortcuts added to the settings system will be editable by users.

Launcher

As with menus, keyboard shortcuts, and the command palette, new items can be added to the application launcher via commands. You can do this by requesting the ILauncher token in your extension:

launcher.add({
  command: commandID,
  category: 'Other',
  rank: 0
});

In addition to providing a command ID, you also provide a category in which to put your item, (e.g. ‘Notebook’, or ‘Other’), as well as a rank to determine its position among other items.

Left/Right Areas

The left and right areas of JupyterLab are intended to host more persistent user interface elements than the main area. That being said, extension authors are free to add whatever components they like to these areas. The outermost-level of the object that you add is expected to be a Lumino Widget, but that can host any content you like (such as React components).

As an example, the following code executes an application command to a terminal widget and then adds the terminal to the right area:

app.commands
  .execute('terminal:create-new')
  .then((terminal: WidgetModuleType.Terminal) => {
    app.shell.add(terminal, 'right');
  });

Status Bar

JupyterLab’s status bar is intended to show small pieces of contextual information. Like the left and right areas, it only expects a Lumino Widget, which might contain any kind of content. Since the status bar has limited space, you should endeavor to only add small widgets to it.

The following example shows how to place a status item that displays the current “busy” status for the application. This information is available from the ILabStatus token, which we reference by a variable named labStatus. We place the statusWidget in the middle of the status bar. When the labStatus busy state changes, we update the text content of the statusWidget to reflect that.

const statusWidget = new Widget();
labStatus.busySignal.connect(() => {
  statusWidget.node.textContent = labStatus.isBusy ? 'Busy' : 'Idle';
});
statusBar.registerStatusItem('lab-status', {
  align: 'middle',
  item: statusWidget
});

Widget Tracker

Often extensions will want to interact with documents and activities created by other extensions. For instance, an extension may want to inject some text into a notebook cell, or set a custom keymap, or close all documents of a certain type. Actions like these are typically done by widget trackers. Extensions keep track of instances of their activities in WidgetTrackers, which are then provided as tokens so that other extensions may request them.

For instance, if you want to interact with notebooks, you should request the INotebookTracker token. You can then use this tracker to iterate over, filter, and search all open notebooks. You can also use it to be notified via signals when notebooks are added and removed from the tracker.

Widget tracker tokens are provided for many activities in JupyterLab, including notebooks, consoles, text files, mime documents, and terminals. If you are adding your own activities to JupyterLab, you might consider providing a WidgetTracker token of your own, so that other extensions can make use of it.