Widget base classes.

These will rarely be used directly by end-users, instead see the “concrete” widgets exported in magicgui.widgets.

All magicgui Widget bases comprise a backend widget that implements one of the widget protocols defined in magicgui.widgets._protocols. The basic composition pattern is as follows:

class Widget:

    def __init__(

         # widget_type is a class, likely from the `backends` module
         # that implements one of the `WidgetProtocols` defined in _protocols.
         widget_type: Type[protocols.WidgetProtocol],

         # backend_kwargs is a key-value map of arguments that will be provided
         # to the concrete (backend) implementation of the WidgetProtocol
         backend_kwargs: dict = dict(),

         # additional kwargs will be provided to the magicgui.Widget itself
         # things like, `name`, `value`, etc...
        # instantiation of the backend widget.
        self._widget = widget_type(**backend_kwargs)

        # ... go on to set other kwargs

These widgets are unlikely to be instantiated directly, (unless you’re creating a custom widget that implements one of the WidgetProtocols… as the backed widgets do). Instead, one will usually instantiate the widgets in magicgui.widgets._concrete which are all available direcly in the magicgui.widgets namespace.

The create_widget() factory function may be used to create a widget subclass appropriate for the arguments passed (such as “value” or “annotation”).


Basic Widget, wrapping a class that implements WidgetProtocol.


Widget with a value, Wraps ValueWidgetProtocol.


Widget with a value, Wraps ButtonWidgetProtocol.


Widget with a constrained value.


Widget with a contstrained value.


Widget with a contstrained value and orientation.


Widget with a value and choices, Wraps CategoricalWidgetProtocol.


Widget that can contain other widgets.