The goal of this repository is to show how to develop custom Jupyter Widgets, presented as short tutorial series.

If you feel something is missing or have an idea for a way to improve this please open an issue

# clone the repository
git clone https://github.com/ianhi/custom-ipywidget-howto.git jupyter-widget-examples

Start with the Hello World and then jump to the topic you are interested in.

• Hello World

Set up the development environment and print to the console.

TODO: add screenshot

# install the dependencies
yarn

# install the Python packages
yarn run install-py

# rebuild the packages
yarn run build-ext

# (optional) link your development version of the extension with JupyterLab
yarn run install:ext

Go to the example directory you want to install, e.g. cd ./hello-world, and run the following commands:

# install the package in development mode
python -m pip install -e .

# (optional) link your development version of the extension with JupyterLab
yarn run install:extension

# rebuild the package
yarn run build

If you want to develop and iterate on the code, you will need to open 2 terminals.

In terminal 1, go to the extension folder and run the following:

yarn watch

Then in terminal 2, start JupyterLab with the watch flag:

jupyter lab --watch

From there, you can change your extension source code, it will be recompiled, and you can refresh your browser to see your changes.

We are using embedme to embed code snippets into the markdown READMEs. If you make changes to the source code, ensure you update the README and run yarn embedme from the root of the repository to regenerate the READMEs.

You can use the TypeScript cookiecutter to quickly bootstrap a new custom widget example:

# install cookiecutter
pip install cookiecutter

# create a new custom widget
cookiecutter https://github.com/jupyter-widgets/widget-ts-cookiecutter

Then answer the prompts to give a new name to the example.

Once your widget is published on pypi.org (outside of this scope), you can install it with the following command:

pip install <published_widget>

To learn widgets I recommend the following resources outside this:

1. Low Level Widget Tutorial
2. Look at existing widgets. Some widgets good widgets to look at are:
   • ipympl
   • ipycanvas
   • ipycytoscape
3. Jupyter-widgets Gitter
4. Jupyter-Widgets Discourse

TODO

This examples repository is a Jupyter project and follows the Jupyter Community Guides and Code of Conduct.