{"id":15020287,"url":"https://github.com/jupyterlab/extension-examples","last_synced_at":"2025-05-14T17:10:41.382Z","repository":{"id":38108676,"uuid":"214395915","full_name":"jupyterlab/extension-examples","owner":"jupyterlab","description":"JupyterLab Extensions by Examples","archived":false,"fork":false,"pushed_at":"2025-02-17T11:20:13.000Z","size":24382,"stargazers_count":481,"open_issues_count":38,"forks_count":180,"subscribers_count":21,"default_branch":"main","last_synced_at":"2025-05-13T15:27:50.504Z","etag":null,"topics":["jupyter","jupyterlab","jupyterlab-extensions"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jupyterlab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":"https://jupyter.org/about#donate"}},"created_at":"2019-10-11T09:24:23.000Z","updated_at":"2025-05-03T06:26:11.000Z","dependencies_parsed_at":"2023-02-19T17:16:01.207Z","dependency_job_id":"b10e2049-ad39-494d-bb93-4dab36117e92","html_url":"https://github.com/jupyterlab/extension-examples","commit_stats":{"total_commits":427,"total_committers":33,"mean_commits":12.93939393939394,"dds":0.7423887587822013,"last_synced_commit":"6a166f180fd559fe2af9288522d8e40268f41e26"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyterlab%2Fextension-examples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyterlab%2Fextension-examples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyterlab%2Fextension-examples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyterlab%2Fextension-examples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jupyterlab","download_url":"https://codeload.github.com/jupyterlab/extension-examples/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254190396,"owners_count":22029632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jupyter","jupyterlab","jupyterlab-extensions"],"created_at":"2024-09-24T19:54:51.779Z","updated_at":"2025-05-14T17:10:41.354Z","avatar_url":"https://github.com/jupyterlab.png","language":"TypeScript","funding_links":["https://jupyter.org/about#donate"],"categories":[],"sub_categories":[],"readme":"# JupyterLab Extensions by Examples\n\n[![Github Actions Status](https://github.com/jupyterlab/extension-examples/workflows/CI/badge.svg)](https://github.com/jupyterlab/extension-examples/actions?query=workflow%3ACI)\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jupyterlab/extension-examples/main?urlpath=lab)\n\n1. [Goal](#tldr)\n1. [Develop by Examples](#develop-by-examples)\n   1. [CodeMirror extension](#codemirror-extension)\n   1. [Commands](#commands)\n   1. [Command Palette](#command-palette)\n   1. [Completer](#completer)\n   1. Main Widget [Content Header](#main-widget-content-header)\n   1. [Context Menu](#context-menu)\n   1. [Custom Log Console](#custom-log-console)\n   1. [Datagrid](#datagrid)\n   1. [Dual Compatibility](#dual-compatibility)\n      1. [Top Area Text Widget](#top-area-text-widget)\n      1. [Shout Button](#shout-button)\n      1. [Clap Button](#clap-button-message)\n   1. [Collaborative Document](#collaborative-document)\n   1. _[Hello World](#hello-world)_\n   1. [Kernel Messaging](#kernel-messaging)\n   1. [Kernel Output](#kernel-output)\n   1. [Launcher](#launcher)\n   1. [Log Messages](#log-messages)\n   1. [Main Menu](#main-menu)\n   1. [Metadata Form](#metadata-form)\n   1. [MIME Renderer](#mime-renderer)\n   1. [Notifications](#notifications)\n   1. [React Widget](#react-widget)\n   1. _[Server Hello World](#server-hello-world)_\n   1. [Settings](#settings)\n   1. [Signals](#signals)\n   1. [State](#state)\n   1. [Toolbar Item](#toolbar-item)\n   1. [Widgets](#widgets)\n1. [Prerequisites](#prerequisites)\n1. [Develop and Use the Examples](#develop-and-use-the-examples)\n1. [Test the Examples](#test-the-examples)\n1. [Install a Published Extension](#install-a-published-extension)\n1. [About JupyterLab](#about-jupyterlab)\n1. [Credits](#credits)\n1. [Community Guidelines and Code of Conduct](#community-guidelines-and-code-of-conduct)\n\n## TL;DR\n\nThe goal of this repository is to show how to develop extensions for [JupyterLab](https://github.com/jupyterlab/jupyterlab), presented as short tutorial series.\n\n**Quick start:** \n- Install, build, and run the `hello-world` extension example in JupyterLab by copying the code below. \n- This corresponds to the first three sections of the [hello-world extension tutorial](hello-world/README.md). Read these sections for additional details on what these commands are doing and how to use the JupyterLab extension template. \n- Continue with the tutorial at the [Modify the extension](hello-world/README.md#modify-the-extension) section, if desired.\n\n```bash\n# clone the repository\ngit clone https://github.com/jupyterlab/extension-examples.git jupyterlab-extension-examples\n\n# go to the extension examples folder\ncd jupyterlab-extension-examples\n\n# create a new environment\nconda env create\n\n# activate the environment\nconda activate jupyterlab-extension-examples\n\n# go to the hello world example\ncd hello-world\n\n# Required to deal with Yarn 3 workspace rules\ntouch yarn.lock\n\n# install the extension in editable mode\npython -m pip install -e .\n\n# install your development version of the extension with JupyterLab\njupyter labextension develop . --overwrite\n\n# build the TypeScript source after making changes\njlpm run build\n\n# start JupyterLab\njupyter lab\n```\n\nThe examples currently target **JupyterLab 4.0 or later**.\n\nIf you would like to use the examples with JupyterLab 3.x, check out the [3.x branch](https://github.com/jupyterlab/extension-examples/tree/3.x).\n\nIf you would like to use the examples with JupyterLab 2.x, check out the [2.x branch](https://github.com/jupyterlab/extension-examples/tree/2.x).\n\nIf you would like to use the examples with JupyterLab 1.x, check out the [1.x branch](https://github.com/jupyterlab/extension-examples/tree/1.x).\n\nNote that the `1.x`, `2.x` and `3.x` branches are not updated anymore.\n\n## Develop by Examples\n\nYou may find it easier to learn how to create extensions _by examples_, instead of going through the documentation.\n\nStart with the [Hello World](hello-world) and then jump to the topic you are interested in.\n\n- [Cell toolbar](cell-toolbar)\n- [CodeMirror extension](codemirror-extension)\n- [Commands](commands)\n- [Command Palette](command-palette)\n- [Completer](completer)\n- Main Widget [Content Header](contentheader)\n- [Context Menu](context-menu)\n- [Custom Log Console](custom-log-console)\n- [Datagrid](datagrid)\n- Dual Compatibility\n  - [Top Area Text Widget](toparea-text-widget)\n  - [Shout Button](shout-button-message)\n  - [Clap Button](clap-button-message)\n- [Collaborative Document](documents)\n- [Hello World](hello-world)\n- [Kernel Messaging](kernel-messaging)\n- [Kernel Output](kernel-output)\n- [Launcher](launcher)\n- [Log Messages](log-messages)\n- [Main Menu](main-menu)\n- [Metadata Form](metadata-form)\n- [MIME Renderer](mimerenderer)\n- [Notifications](notifications)\n- [React Widget](react-widget)\n- [Server Hello World](server-extension)\n- [Settings](settings)\n- [Signals](signals)\n- [State](state)\n- [Toolbar item](toolbar-button)\n- [Widgets](widgets)\n\nYou can expect from each example:\n\n- An explanation of its functionality.\n- An image or screencast showing its usage.\n- The list of used JupyterLab API and Extension Points.\n- Explanations of the internal working, illustrated with code snippets.\n\nWe have structured the examples based on the [extension points](https://jupyterlab.readthedocs.io/en/stable/extension/extension_points.html). Browse the previews below or skip them and [jump directly to the sections for developers](#prerequisites).\n\nYou are welcome to open any [issue](https://github.com/jupyterlab/extension-examples/issues) or [pull request](https://github.com/jupyterlab/extension-examples/pulls).\n\n### [Cell toolbar](cell-toolbar)\n\nAdd a command button to the cell toolbar.\n\n[![Cell toolbar](cell-toolbar/preview.gif)](cell-toolbar)\n\n### [CodeMirror extension](codemirror-extension)\n\nAdd a configurable CodeMirror extension.\n\n[![CodeMirror extension](codemirror-extension/preview.png)](codemirror-extension)\n\n### [Commands](commands)\n\nExtend the main app with a Command.\n\n[![Command example](commands/preview.png)](commands)\n\n### [Command Palette](command-palette)\n\nRegister commands in the Command Palette.\n\n[![Command Palette](command-palette/preview.png)](command-palette)\n\n### [Completer](completer)\n\nCustomize tab autocomplete data sources.\n\n[![Completer](completer/preview.png)](completer)\n\n### Main Widget [Content Header](contentheader)\n\nPut widgets at the top of a main JupyterLab area widget.\n\n[![contentHeader](contentheader/preview.gif)](contentheader)\n\n### [Context Menu](context-menu)\n\nAdd a new button to an existent context menu.\n\n[![Context Menu](context-menu/preview.gif)](context-menu)\n\n### [Custom Log Console](custom-log-console)\n\nCreate a new log console.\n\n[![Custom Log Console](custom-log-console/preview.gif)](custom-log-console)\n\n### [Datagrid](datagrid)\n\nDisplay a Datagrid as a Lumino Widget.\n\n[![Datagrid](datagrid/preview.gif)](datagrid)\n\n### Dual Compatibility\n\nThe dual compatibility examples demonstrates how to design an extension that can be\nintegrated similtaneously in JupyterLab and Jupyter Notebook v7+.\n\nThey are listed from the simplest to the most advanced case:\n\n- [Top Area Text Widget](#top-area-text-widget): Example working right away in both frontends.\n- [Shout Button](#shout-button): Example with a part only available in JupyterLab\n- [Clap Button](#clap-button-message): Example with elements added differently depending on\n  the frontends used.\n\n#### [Top Area Text Widget](toparea-text-widget)\n\nA very simple example that adds a basic text widget to the top area. See [related video.](https://www.youtube.com/watch?v=mqotG1MkHa4).\nThis example is part of the [Extension Compatibility Guide](https://jupyterlab.readthedocs.io/en/latest/extension/extension_multiple_ui.html).\n\n[![Top Area Text Widget](toparea-text-widget/preview.jpg)](toparea-text-widget)\n\n#### [Shout Button](shout-button-message)\n\nThis example shows dual compatibility: Make an extension that is compatible\nwith both JupyterLab and Jupyter Notebook by using optional features. Adds\na shout button to the right sidebar, and if running in JupyterLab, also adds\na status bar widget. This example is part of the [Extension Compatibility Guide](https://jupyterlab.readthedocs.io/en/latest/extension/extension_multiple_ui.html).\nRead more about this example on that page.\n\n[![Dual compatibility shout button](shout-button-message/preview.jpg)](shout-button-message)\n\n#### [Clap Button](clap-button-message)\n\nThis example shows an alternate method for achieving dual compatibility: Make an\nextension that is compatible with both JupyterLab and Jupyter Notebook by exporting\nmultiple plugins and using \"required\" features to select different behaviors. Adds a clap button to\nthe top area (in JupyterLab) or the right sidebar (Jupyter Notebook). This example is part\nof the [Extension Compatibility Guide](https://jupyterlab.readthedocs.io/en/latest/extension/extension_multiple_ui.html).\nRead more about this example on that page.\n\n[![Dual Compatibility Clap Button](clap-button-message/preview.png)](clap-button-message)\n\n### [Collaborative Document](documents)\n\nCreate new documents and make them collaborative.\n\n[![Documents](documents/preview.png)](documents)\n\n### [Hello World](hello-world)\n\nSet up the development environment and print to the console.\n\n[![Hello World](hello-world/preview.png)](hello-world)\n\n### [Kernel Messaging](kernel-messaging)\n\nInteract with a kernel from an extension.\n\n[![Kernel Messages](kernel-messaging/preview.gif)](kernel-messaging)\n\n### [Kernel Output](kernel-output)\n\nRender kernel messages in an OutputArea.\n\n[![OutputArea class](kernel-output/preview.gif)](kernel-output)\n\n### [Launcher](launcher)\n\nStart your extension from the Launcher.\n\n[![Launcher](launcher/preview.gif)](launcher)\n\n### [Log Messages](log-messages)\n\nSend a log message to the log console.\n\n[![Log Messages](log-messages/preview.gif)](log-messages)\n\n### [Main Menu](main-menu)\n\nAdd a Menu to the main app.\n\n[![Main Menu](main-menu/preview.png)](main-menu)\n\n### [Metadata Form](metadata-form)\n\nAdd user interface to edit cell or notebook metadata.\n\n[![Metadata Form](metadata-form/preview.gif)](metadata-form)\n\n### [MIME Renderer](mimerenderer)\n\nAdd a MIME renderer for mp4 content to the application.\n\n[![MIME Renderer](mimerenderer/preview.png)](mimerenderer)\n\n### [Notifications](notifications)\n\nEmit notifications.\n\n[![Notifications](notifications/preview.gif)](notifications)\n\n### [React Widget](react-widget)\n\nCreate a React.js Widget in JupyterLab.\n\n[![react-widget](react-widget/preview.gif)](react-widget)\n\n### [Server Hello World](server-extension)\n\nCreate a minimal extension with backend (i.e. server) and frontend parts.\n\n[![Server Hello World](server-extension/preview.png)](server-extension)\n\n### [Settings](settings)\n\nCreate and use new Settings for your extension.\n\n[![Settings](settings/preview.gif)](settings)\n\n### [Signals](signals)\n\nUse Signals to allow Widgets communicate with each others.\n\n[![Button with Signal](signals/preview.png)](signals)\n\n### [State](state)\n\nUse State persistence in an extension.\n\n[![State](state/preview.gif)](state)\n\n### [Toolbar Item](toolbar-button)\n\nAdd a new button to the notebook toolbar.\n\n[![Toolbar button](toolbar-button/preview.gif)](toolbar-button)\n\n### [Widgets](widgets)\n\nAdd a new Widget element to the main window.\n\n[![Custom Tab](widgets/preview.png)](widgets)\n\n## Prerequisites\n\nWriting an extension requires basic knowledge of JavaScript, Typescript and potentially Python.\n\n_Don't be scared of Typescript, even if you never coded in TypeScript before you touch\nJupyterLab you may find it easier to understand than pure JavaScript if you have a\nbasic understanding of object oriented programming and types._\n\nThese examples are developed and tested on top of JupyterLab.\nYou can create a [conda](https://docs.conda.io/en/latest/miniconda.html) environment to get started\nafter cloning this repository.\n\n```bash\nconda env create \u0026\u0026 \\\n  conda activate jupyterlab-extension-examples\n```\n\n\u003e The previous command will use the [environment.yml](https://github.com/jupyterlab/extension-examples/blob/main/environment.yml) file as requirements for the environment.\n\n## Develop and Use the Examples\n\n### Build and Install all Examples at once\n\n```bash\njlpm\njlpm build-ext\njlpm install-py\njlpm install-ext\njupyter lab\n```\n\nTo rebuild all the extensions:\n\n```bash\njlpm build-ext\n```\n\nTo clean the lib folders:\n\n```bash\njlpm clean-ext\n```\n\n### Build and Install one Example\n\nGo to the example directory you want to install, e.g. `cd ./hello-world`, and run the following commands:\n\n```bash\ntouch yarn.lock\npip install -e .\njupyter labextension develop . --overwrite\n```\n\nRebuild the extension:\n\n```bash\njlpm run build\n```\n\nYou can now start JupyterLab and check if your extension is working fine:\n\n```bash\njupyter lab\n```\n\n### Change the Sources\n\nIf you want to develop and iterate on the code, you will need to open 2 terminals.\n\nIn terminal 1, go to the extension folder and run the following:\n\n```bash\njlpm watch\n```\n\nThen in terminal 2, start JupyterLab:\n\n```bash\njupyter lab\n```\n\nFrom there, you can change your extension source code, it will be recompiled,\nand you can refresh your browser to see your changes.\n\nWe are using [embedme](https://github.com/zakhenry/embedme) to embed code snippets into the markdown READMEs. If you make changes to the source code, ensure you update the README and run `jlpm embedme` from the root of the repository to regenerate the READMEs.\n\n### Update extension template\n\nExecute from the example root folder:\n\n```sh\n./scripts/update-template.sh\n```\n\nThen fix the conflicts.\n\n## Test the Examples\n\nThe examples are automatically tested for:\n\n- Homogeneous configuration:\n  Configuration files are compared to the reference ones of the _hello-world_ example\n- TypeScript code lint\n- Installation in JupyterLab:\n  The installation is checked by listing the installed extension and running JupyterLab with the helper `python -m jupyterlab.browser_check`\n- Integration test:\n  Those tests are emulating user action in JupyterLab to check the extension is behaving as expected.\n  The tests are defined in the `ui-tests` subfolder within each example.\n  This is possible thanks to a tool called [playwright](https://playwright.dev/).\n\n## Install a Published Extension\n\nOnce your extension is published on [pypi.org](https://pypi.org/) (outside of this scope), you can install it\nwith the following command:\n\n```bash\npip install \u003cpublished_extension\u003e\n```\n\n## About JupyterLab\n\nJupyterLab can be used as a platform to combine existing data-science components into a\nnew powerful application that can be deployed remotely to many users. Some of the higher\nlevel components that can be used are text editors, terminals, notebooks, interactive widgets,\nfilebrowser, renderers for different file formats that provide access to an enormous ecosystem\nof libraries from different languages.\n\nComplementary to these examples, you can rely on the official JupyterLab documentation.\n\n- [Extension Developer Guide](https://jupyterlab.readthedocs.io/en/stable/extension/extension_dev.html)\n- [Common Extension Points](https://jupyterlab.readthedocs.io/en/stable/extension/extension_points.html)\n- [Astronomy Picture of the Day JupyterLab Extension](https://jupyterLab.readthedocs.io/en/stable/extension/extension_tutorial.html)\n\n## Credits\n\nWe would like to thank [MMesch](https://github.com/MMesch) for [initiating this work](https://github.com/MMesch/labextension_tutorial), as well as everyone else who contributed!\n\n## Community Guidelines and Code of Conduct\n\nThis examples repository is a Jupyter project and follows the Jupyter\n[Community Guides and Code of Conduct](https://jupyter.readthedocs.io/en/latest/community/content-community.html).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjupyterlab%2Fextension-examples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjupyterlab%2Fextension-examples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjupyterlab%2Fextension-examples/lists"}