User Guide

ipywidgets changelog

expand icon

ipywidgets changelog

A summary of changes in ipywidgets. For more detailed information, see the issues and pull requests for the appropriate milestone on GitHub.

7.0

To see the full list of pull requests and issues, see the 7.0 milestone on GitHub.

Major user-visible changes in ipywidgets 7.0 include:

  • Widgets are now displayed in the output area in the classic notebook and are treated as any other output. This allows the widgets to work more naturally with other cell output. To delete a widget, clear the output from the cell. Output from functions triggered by a widget view is appended to the output area that contains the widget view. This means that printed text will be appended to the output, and calling clear_output() will delete the entire output, including the widget view. (#1274, #1353)
  • Removed the version validation check since it was causing too many false warnings about the widget javascript not being installed or the wrong version number. It is now up to the user to ensure that the ipywidgets and widgetsnbextension packages are compatible. (#1219)
  • The documentation theme is changed to the new standard Jupyter theme. (#1363)
  • The layout and style traits can be set with a dictionary for convenience, which will automatically converted to a Layout or Style object, like IntSlider(layout={'width': '100%'}, style={'handle_color': 'lightgreen'}). (#1253)
  • The Select widget now is a listbox instead of a dropdown, reverting back to the pre-6.0 behavior. (#1238)
  • The Select and SelectMultiple widgets now have a rows attribute for the number of rows to display, consistent with the Textarea widget. The layout.height attribute overrides this to control the height of the widget. (#1250)
  • Selection widgets (Select, Dropdown, ToggleButtons, etc.) have new .value, .label, and .index traits to make it easier to access or change the selected option. (#1262, #1513)
  • Selection container widgets (Accordion, Tabs) can have their .selected_index set to None to deselect all items. (#1495)
  • The Play widget range is now inclusive (max value is max, instead of max-1), to be consistent with Sliders
  • The Play widget now has an optional repeat toggle button (visible by default). (#1190)
  • A refactoring of the text, slider, slider range, and progress widgets in resulted in the progress widgets losing their step attribute (which was previously ignored), and a number of these widgets changing their _model_name and/or _view_name attributes (#1290)
  • The Checkbox description is now on the right of the checkbox and is clickable. The Checkbox widget has a new indent attribute (defaults to True) to line up nicely with controls that have descriptions. To make the checkbox align to the left, set indent to False. (#1346)
  • A new Password widget, which behaves exactly like the Text widget, but hides the typed text: Password(). (#1310)
  • A new SelectionRangeSlider widget for selecting ranges from ordered lists of objects. For example, this enables having a slider to select a date range. (#1356)
  • The Label widget now has no width restriction. (#1269)
  • The description width is now configurable with the .style.description_width attribute (#1376)
  • ToggleButtons have a new .style.button_width attribute to set the CSS width of the buttons. Set this to 'initial' to have buttons that individually size to the content width. (#1257)
  • The readout_format attribute of number sliders now validates its argument. (#1550)
  • The IntRangeSlider widget now has a .readout_format trait to control the formatting of the readout. (#1446)
  • The Text, Textarea, IntText, BoundedIntText, FloatText, and BoundedFloatText widgets all gained a continuous_update attribute (defaults to True for Text and TextArea, and False for the others). (#1545)
  • The IntText, BoundedIntText, FloatText, and BoundedFloatText widgets are now rendered as HTML number inputs, and have a step attribute that controls the resolution. (#1545)
  • The Text.on_submit callback is deprecated; instead, set continuous_update to False and observe the value attribute: mywidget.observe(callback, 'value'). The Textarea.scroll_to_bottom method was removed. (#1545)
  • The msg_throttle attribute on widgets is now gone, and the code has a hardcoded message throttle equivalent to msg_throttle=1. (#1557)
  • Using function annotations to specify interact controls for a function is now deprecated and will be removed in a future version of ipywidgets. (#1292)
  • There are now two simple ways to embed widgets in an HTML page: with a simple script tag that does not use require.js and does not support anything but the basic widgets, and a require module that does support custom widgets. See the migration guide for more details. (#1615, #1629, #1630)

If you are developing a custom widget or widget manager, here are some major changes that may affect you. The migration guide also walks through how to upgrade a custom widget.

  • On the Python/kernel side:
    • The Python @register decorator for widget classes no longer takes a string argument, but registers a widget class using the _model_* and _view_* traits in the class. Using the decorator as @register('name') is deprecated and should be changed to just @register. #1228, #1276
    • Widgets will now need correct _model_module and _view_module Unicode traits defined.
    • Selection widgets now sync the index of the selected item, rather than the label. (#1262)
    • The Python ipywidget.domwidget.LabeledWidget is now ipywidget.widget_description.DescriptionWidget, and there is a new ipywidget.widget_description.DescriptionStyle that lets the user set the CSS width of the description.
    • Custom serializers can now return a structure that contains binary objects (memoryview, bytearray, or Python 3 bytes object). In this case, the sync message will be a binary message, which is much more efficient for binary data than base64-encoding. The Image widget now uses this binary synchronization. (#1194, #1595, #1643)
  • On the Javascript side:
    • The jupyter-js-widgets Javascript package has been split into @jupyter-widgets/base package (containing base widget classes, the DOM widget, and the associated layout and style classes), and the @jupyter-widgets/controls package (containing the rest of the Jupyter widgets controls). Authors of custom widgets will need to update to depend on @jupyter-widgets/base instead of jupyter-js-widgets (if you use a class from the controls package, you will also need to depend on @jupyter-widgets/controls). See the cookie cutter to generate a simple example custom widget using the new packages.
    • Custom serializers in Javascript are now synchronous, and should return a snapshot of the widget state. The default serializer makes a copy of JSONable objects. (#1270)
    • Custom serializers can now return a structure that contains binary objects (ArrayBuffer, DataView, or a typed array such as Int8Array, Float64Array, etc.). In this case, the sync message will be a binary message, which is much more efficient for binary data than base64-encoding. The Image widget now uses this binary synchronization. (#1194, #1643)
    • A custom serializer is given the widget instance as its second argument, and a custom deserializer is given the widget manager as its second argument.
    • The Javascript model .id attribute has been renamed to .model_id to avoid conflicting with the Backbone .id attribute. (#1410)
  • Regarding widget managers and the syncing message protocol:
    • The widget protocol was significantly overhauled. The new widget messaging protocol (version 2) is specified in the version 2 protocol documentation.
    • Widgets are now displayed with a display_data message instead of with a custom comm message. See the ipywidgets implementation for an example. (#1274)
    • Custom widget managers are now responsible completely for loading widget model and view classes. Widget managers should provide an output model and view class appropriate for their environment so that the Output widget works. (#1313)
    • The widget manager clear_state method no longer has a commlessOnly argument. All models in the widget manager will be closed and cleared when clear_state is called. (#1354)

6.0

Major user-visible changes in ipywidgets 6.0 include:

  • Rendering of Jupyter interactive widgets in various web contexts

    sphinx documentation: http://ipywidgets.readthedocs.io/en/latest/examples/Widget%20List.html nbviewer: http://nbviewer.jupyter.org/github/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Widget%20List.ipynb Static web pages: http://jupyter.org/widgets

  • Addition of a DatePicker widget in the core widget collection.

  • Changes to the automatic control generation syntax in @interact, inspired by the Sage interact syntax.

  • Removal of APIs which had been deprecated in 5.0, including top-level styling in attributes of DOMWidgets and some corner cases in the behavior of @interact.

  • A new API for custom styling of widgets is provided, through a top-level style attribute. For example, the color of a slider handler can be set by slider.style.handle_color.

  • Removal of the Proxy and PlaceProxy widgets.

  • Removal of the deprecated FlexBox widget. Use the Box, HBox, or VBox widgets instead. Various flex properties can be set using the layout attribute.

  • Removal of the deprecated Latex widget. Use the new HTMLMath widget with Latex math inside $ or $$ delimiters instead.

  • Removal of the deprecated layout properties on a widget such as .width, .height, etc. Use the layout attribute with a Layout widget to manage various layout properties instead.

  • The Label widget now has styling to make it consistent with labels on various widgets. To have freeform text with mathematics, use the new HTMLMath widget.

  • Removal of the button_style attribute of the Dropdown widget

  • Addition of an OutputWidget for capturing output and rich display objects. @interact has changed to use an OutputWidget for function output instead of overwriting the output area of a cell.

  • The jupyter-js-widgets Javascript implementation now relies on the PhosphorJS framework for the management of rich layout and a better integration of JupyterLab.

  • Numerous bug fixes.

Note for custom widget authors:

ipywidgets 6.0 breaks backward compatibility with respect to the handling of default values of the JavaScript side. Now, the default values for core widget models are specified with a default() method returning a dictionary instead of a default dictionary attribute. If you want your library to be backwards compatible with ipywidgets 5.x, you could use _.result like this:

...
defaults: function() {
        return _.extend(_.result(this, 'widgets.DOMWidgetModel.prototype.defaults'), {
          ....
        })
},
...

This should not have an impact when using your custom widgets in the classic notebook, but will be really important when deploying your interactive widgets in web contexts.

5.x

4.1.x

4.1.1

4.1.0

4.0.x

4.0.3

Bump version with miscellaneous bug fixes.

4.0.2

Add README.rst documentation.

4.0.1

Remove ipynb checkpoints.

4.0.0

First release of ipywidgets as a standalone package.