CheckButtonGroup#

Download this notebook from GitHub (right-click to download).


import panel as pn
import panel_material_ui as pmui

pn.extension()

The CheckButtonGroup widget allows users to select multiple options from a list by toggling the corresponding buttons. It falls into the broad category of multi-option selection widgets that provide a compatible API and include the MultiSelect, CrossSelector and CheckBoxGroup widgets that share a compatible API.

The CheckButtonGroup is built on top of the Material UI ToggleButtonGroup.

Parameters:#

For more details on customization options, see the customization guides.

Core#

  • disabled (bool): If True, the widget is not interactive.

  • options (list or dict): The available options to choose from. Can be a list of strings or a dictionary mapping labels to values.

  • value (list): The currently selected options.

Display#

  • color (str): The color theme for the buttons

  • description (str | Bokeh Tooltip | pn.widgets.TooltipIcon): A description which is shown when the widget is hovered.

  • label (str): The title of the widget

  • loading (bool): If True, displays a loading spinner over the component.

  • orientation (str, default=’horizontal’): Button group orientation, either ‘horizontal’ or ‘vertical’

  • size: (str, default=’medium’): The size of the widget. One of “small”, “medium” or “large”.

Styling#

  • sx (dict): Component level styling API.

  • theme_config (dict): Theming API.

Aliases#

For compatibility with Panel certain parameters are allowed as aliases:

  • button_style: Alias for variant

  • button_type: Alias for color

  • name: Alias for label


Basic Usage#

Create a CheckButtonGroup with a list of options. Users can select multiple items by toggling the corresponding buttons:

checkbutton_group = pmui.CheckButtonGroup(label='Check Button Group', value=['Apple', 'Pear'], options=['Apple', 'Banana', 'Pear', 'Strawberry'])

checkbutton_group

The value parameter returns a list of the currently selected options:

checkbutton_group.value
['Apple', 'Pear']

Dictionary Options#

You can provide options as a dictionary where keys are the displayed labels and values are the actual option values:

dict_group = pmui.CheckButtonGroup(
    label='Check Button Group', value=['A', 'P'], options={'Apple': 'A', 'Banana': 'B', 'Pear': 'P', 'Strawberry': 'S'},
)

dict_group

Let’s observe how the value parameter reflects the selected dictionary values (not the labels):

pn.pane.Str(dict_group.param.value)

Orientation#

Control the layout of buttons using the orientation parameter:

pmui.Column(
    pmui.CheckButtonGroup(label='Horizontal Group', orientation="horizontal", value=['Apple', 'Pear'], options=['Apple', 'Banana', 'Pear', 'Strawberry']),
    pmui.CheckButtonGroup(label='Vertical Group', orientation="vertical", value=['Apple', 'Pear'], options=['Apple', 'Banana', 'Pear', 'Strawberry'])
)

Styles#

The color of the button can be set by selecting one of the available color values and the variant to one of 'contained', 'solid' or 'outline':

pmui.Row(
    *(pmui.Column(*(
        pmui.CheckButtonGroup(
            label=color, color=color, variant=variant, options=['Foo', 'Bar', 'Baz'], value=['Bar']
        )
        for color in pmui.Button.param.color.objects
    ))
    for variant in pmui.Button.param.variant.objects)
)

Size Options#

Adjust the CheckButtonGroup size using the size parameter:

pmui.FlexBox(
    *(pmui.CheckButtonGroup(label=size, size=size, value=['Apple', 'Pear'], options=['Apple', 'Banana', 'Pear', 'Strawberry']) for size in pmui.CheckButtonGroup.param.size.objects)
)

Disabled and Loading States#

Like other widgets, the CheckButtonGroup can be disabled to prevent interaction and/or show a loading indicator:

pmui.CheckButtonGroup(label='Disabled Group', disabled=True, loading=True, value=['Apple', 'Pear'], options=['Apple', 'Banana', 'Pear', 'Strawberry'])

Example: Interactive Pizza Order Form#

Let’s create a practical example showing how CheckBoxGroup can be used in a real application. This pizza ordering interface demonstrates real-time updates based on user selections:

import panel as pn
import panel_material_ui as pmui

pn.extension()

toppings = pmui.CheckButtonGroup(
    label="Select your toppings:",
    options=['Pepperoni', 'Mushrooms', 'Bell Peppers', 'Onions', 'Olives', 'Extra Cheese'],
    value=['Pepperoni', 'Onions'],
    sizing_mode="stretch_width",
)

def create_order_summary(toppings):
    summary = f"## 🧺 Your Pizza Order\n\n"
    summary += f"• Toppings: {', '.join(toppings) if toppings else 'None'}\n"
    
    base_price = 12.99
    topping_price = len(toppings) * 1.50
    total = base_price + topping_price
    summary += f"\n**Total: ${total:.2f}**"
    
    return summary

order_summary = pn.bind(create_order_summary, toppings=toppings)

pmui.Column(
    "## 🍕 Pizza Order Form",
    toppings,
    "---",
    order_summary,
    width=800
)

API Reference#

Parameters#

pmui.CheckButtonGroup(label='Check Button Group', value=['Apple', 'Pear'], options=['Apple', 'Banana', 'Pear', 'Strawberry']).api(jslink=True)

References#

Discover more on using widgets to add interactivity to your applications in the how-to guides on interactivity.

Learn how to set up callbacks and (JS-)links between parameters or how to use them as part of declarative UIs with Param.

See also the Material UI ToggleButtonGroup Reference and API documentation for inspiration.


Download this notebook from GitHub (right-click to download).