matplotlib.widgets.CheckButtons#

class matplotlib.widgets.CheckButtons(ax, labels, actives=None, *, layout=None, useblit=True, label_props=None, frame_props=None, check_props=None)[source]#

Bases: _Buttons

A GUI neutral set of check buttons.

For the check buttons to remain responsive you must keep a reference to this object.

Connect to the CheckButtons with the on_clicked method.

Attributes:

axAxes

The parent Axes for the widget.

labelslist of Text

The text label objects of the check buttons.

Add check buttons to Axes instance ax.

Parameters:

axAxes

The parent Axes for the widget.

labelslist of str

The labels of the check buttons.

activeslist of bool, optional

The initial check states of the buttons. The list must have the same length as labels. If not given, all buttons are unchecked.

layoutNone or "vertical" or "horizontal" or (int, int), default: None

The layout of the check buttons. Options are:

• None: Use legacy vertical layout (default).

• "vertical": Arrange buttons in a single column with dynamic positioning based on text widths.

• "horizontal": Arrange buttons in a single row with dynamic positioning based on text widths.

• (rows, cols) tuple: Arrange buttons in a grid with the specified number of rows and columns. Buttons are placed left-to-right, top-to-bottom with dynamic positioning.

The layout options "vertical", "horizontal" and (rows, cols) create mtext.Text objects to determine exact text sizes, and then they are added to the Axes. This is usually okay, but may cause side-effects and has a slight performance impact. Therefore the default None value avoids this.

Added in version 3.11.

useblitbool, default: True

Use blitting for faster drawing if supported by the backend. See the tutorial Faster rendering by using blitting for details.

Added in version 3.7.

label_propsdict of lists, optional

Dictionary of Text properties to be used for the labels. Each dictionary value should be a list of at least a single element. If the list is of length M, its values are cycled such that the Nth label gets the (N mod M) property.

Added in version 3.7.

frame_propsdict, optional

Dictionary of scatter Collection properties to be used for the check button frame. Defaults (label font size / 2)**2 size, black edgecolor, no facecolor, and 1.0 linewidth.

Added in version 3.7.

check_propsdict, optional

Dictionary of scatter Collection properties to be used for the check button check. Defaults to (label font size / 2)**2 size, black color, and 1.0 linewidth.

Added in version 3.7.

clear()[source]#

Uncheck all checkboxes.

get_checked_labels()[source]#

Return a list of labels currently checked by user.

get_status()[source]#

Return a list of the status (True/False) of all of the check buttons.

set_active(index, state=None)[source]#

Modify the state of a check button by index.

Callbacks will be triggered if eventson is True.

Parameters:

indexint

Index of the check button to toggle.

statebool, optional

If a boolean value, set the state explicitly. If no value is provided, the state is toggled.

Raises:

ValueError

If index is invalid.

TypeError

If state is not boolean.

set_check_props(props)[source]#

Set properties of the check button checks.

Added in version 3.7.

Parameters:

propsdict

Dictionary of Collection properties to be used for the check button check.

set_frame_props(props)[source]#

Set properties of the check button frames.

Added in version 3.7.

Parameters:

propsdict

Dictionary of Collection properties to be used for the check button frames.

Examples using matplotlib.widgets.CheckButtons#

[]

Check buttons

Check buttons