ipywidgets 5.0 Release Document

What’s New?

This release of ipywidgets focuses heavily on the Javascript portion of the widget framework, decoupling the widgets from the notebook frontend. It is now possible to embed widgets in a non-notebook context. Not only that, but said widgets can be made “live” (connected to a kernel) by integrating them with jupyter-js-services. The goal of these features is to enable complex widgets to be made into standalone applications.

Changes have been made to the backend to reduce the surface area of the API. More specifically, most of the widget styling API as it existed in 4.x has be deprecated in favor of a new API, the Layout API, where every widget has a mutable instance of a Layout object that allows box and flex box model attributes to be set on the widget. The reason for minimizing the API is to prepare for the “Small Split” (ipywidgets 6.0), in which the Javascript will be separated from the Python and then refactored and released as “jupyter-js-widgets” on NPM.

Additionally, widget alignment and styling has been improved.

Migration to ipywidgets 5.0

Most of the widget code from the ipywidgets 4.x series should still work in ipywidgets 5.0. However, much of the API has been deprecated and using it will invoke noisey warning messages.

• For IPython 3.x widgets to ipywidgets 4.0 (the first standalone release of the widgets), see this wiki page
• For IPython 2.x widgets to IPython 3.x widget, see this wiki page

User Focused

• The default widths for widgets have changed so there are short and long widgets, which share widths (ref #208, #221)
• The padding and margin of the widget area has been changed so widgets left align to the edge of cells (ref #211)
• All widgets now have a default margin of 2px (ref #216)
• All of the 4.x styling API has been deprecated in favor of the new Layout based API (ref #219, #272, #298, #309)
• The css class names applied to widgets have been changed so that they no longer have an ipy prefix (ref #326)
• ipywidgets has upgraded its traitlets dependency to traitlets 4.1. The new traitlets API should be used because the old one is deprecated (ref #327)
• Checkbox widgets now display their description to the right of the checkbox rather than the left, and the description width is fixed.
• The visible property no longer determines the visibilty of a widget. To hide a widget while allowing it to take up space in the layout, set w.layout.visibility = 'hidden'; to show the widget, set w.layout.visibility = 'visible'. To hide the widget and remove it from the layout, set w.layout.display = 'none'; to make it visible again, set w.layout.display back to the value it had before you hid it (typically either 'flex' or '', though the best approach is probably to cache the original value).

Widget Author Focused

• The deprecated Javascript function WidgetManager.create_model was removed, use WidgetManager.new_widget or WidgetManager.new_model instead (ref #217)
• The deprecated Javascript function WidgetView.after_displayed was removed, use the WidgetView.displayed promise or displayed event instead (ref #217)
• Widget definitions in the frontend are now expected to have default values defined (ref #304)

Kernel Author Focused

• Kernel authors no longer need to implement the CommInfo widget, a comm_info message is now built into the Jupyter msg spec. (ref #175)
• Jupyter is used instead of IPython in the backend widget registry (ref #299)
• A new comm is used to cross validate the frontend version to the backend version once the frontend is loaded. Kernel authors will need to implement a target handler for this comm, and send their expected front-end version once a comm has been opened. Optionally the kernel can then wait for the response from the frontend, letting the kernel know whether or not it’s compatible (ref #303, #319)
• The widget comm target name was renamed to jupyter.widget (ref #311)