Create your own custom Python widget

Tutorials

Tutorial 1/2 - Use raw JavaScript to create custom Python widget

1. Fork and clone the repository to your local computer.
2. Activate the appropriate conda environment.
3. Run pip install anywidget.
4. Open the cloned repo with your favorite IDE (e.g., VS Code).
5. Run examples in the notebooks folder.

Tutorial 2/2 - Use React to create a custom Python widget

In the previous tutorial, you learned how to create a module by importing JavaScript and CSS files. However, defining all logic within a single JavaScript file—such as maintaining global variables—can quickly become challenging, especially if you have many buttons and forms to manage.

React is a framework that enables you to create complex UIs and handle user actions in a much more concise and maintainable way. The downside is that you need to learn and use its conventions and tooling, but in the long run, it's a worthwhile investment. Full documentation is available here.

1. Get the latest update from the upstream repository using git pull.
2. Have npm installed. You can install it along with Node.js by running python -m nodeenv -p --node=20.16.0. npm is a package manager for JavaScript, similar to pip for Python. Node.js is a JavaScript library, mainly used for server-side development.
3. Run npm run dev to start a development server that automatically bundles your React code.
   This will watch your files and rebuild the JavaScript bundle whenever you make changes. Bundling is necessary because React/TypeScript code must be compiled into browser-compatible JavaScript for use in notebooks.
4. Open a new Terminal window and activate the relevant Conda environment.
5. Run pip install -e . from the project root to install your widget in "editable" mode.
   The -e flag ensures that updates to your Python code are immediately available without reinstalling the package.
6. Open example.ipynb in the top-level project directory.
7. Notice that MyWidget is defined under src/__init__.py.
8. Notice that js/awesome_widget.css and js/awesome_widget.tsx are automatically rendered to src/static/awesome_widget.css and src/static/awesome_widget.js.
9. To modify or add more styles, edit js/awesome_widget.css. Restart the Jupyter notebook to see your changes.
10. Future React code can be introduced in js/awesome_widget.tsx. Since the current tutorial isn't for React, for more React tutorials, please refer to the below documentation. Also check the FAQs section below.

Documentation

• anywidget
• react

Frequently asked questions

anywidget

• What is traitlets?

  • It is a Python library that enables you to create objects with typed attributes that can be synchronized between Python and JavaScript. For example, you can have computed variables in Python available in JavaScript, and vice versa.

• What is a trait?

  • Simply put, it is a powerful "variable" (attribute) that can be synchronized between Python and JavaScript, notifies when its value changes, and can have a default value if needed.

• What types can be used with traitlets?

  • traitlets supports common data types like Int, Float, Unicode, Bool, List, Dict, and more. You can also create custom trait types if needed.

• What does model.set do in the JavaScript code?

  • It sets a new value for a synced trait on the frontend model (JavaScript side), which can then be synced back to Python.

• What does model.save_changes() do?

  • It pushes the updated values from the frontend model back to Python, ensuring the backend sees the new values.

• Can I observe trait changes in Python?

  • Yes. You can use .observe in Python to run a function whenever a trait's value changes.

• Why do I need to tag a trait with sync=True?

  • This tells the system to synchronize that trait between Python and JavaScript.