MultiChoice#

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

This component replaces a classic Panel component

This component is being integrated into Panel. Starting with Panel 1.10 it is available as pn.ui.MultiChoice, documented in the Panel reference, and supersedes the classic pn.widgets.MultiChoice. On Panel 1.10 and later, prefer the panel.ui namespace.

import panel as pn
import panel_material_ui as pmui

pn.extension()

The MultiChoice widget allows selecting multiple values from a list of options. It falls into the broad category of multi-value, option-selection widgets that provide a compatible API and include the MultiSelect, CrossSelector, CheckBoxGroup and CheckButtonGroup widgets. The MultiChoice widget provides a much more compact UI than MultiSelect.


Discover more on using widgets to add interactivity to your applications in the how-to guides on interactivity. Alternatively, learn how to set up callbacks and (JS-)links between parameters or how to use them as part of declarative UIs with Param.




Parameters:#


For details on other options for customizing the component see the customization guides.




Core#


    

  • bookmarks (list): List of bookmarked options that are rendered first.
    • 

  • disabled (boolean): Whether the widget is editable
    • 

  • disabled_options (list): List of options that are disabled.
    • 

  • filter_on_search (boolean): Whether to filter or highlight the matching options on search.
    • 

  • option_limit (int): Maximum number of options to display at once.
    • 

  • options (list or dict): List or dictionary of options
    • 

  • search_option_limit (int): Maximum number of options to display at once if search string is entered.
    • 

  • max_items (int): Maximum number of options that can be selected
    • 

  • searchable (boolean): Whether to render a search box.
    • 

  • value (list): Currently selected option values
    • 







Display#


    

  • color (str): The color variant of the input and indicating the selected item(s), which must be one of 'default' (white), 'primary' (blue), 'success' (green), 'info' (yellow), 'light' (light), or 'danger' (red).
    • 

  • delete_button (boolean): Whether to display a button to delete a selected option
    • 

  • dropdown_height (int | None): Height of the select dropdown.
    • 

  • error_state (boolean): Whether to display in error state.
    • 

  • helper_text (str): Helper text displayed below the input field.
    • 

  • label (str): The title of the widget
    • 

  • placeholder (str): String displayed when no selection has been made.
    • 

  • solid (boolean): Whether to display widget with solid or light style.
    • 

  • variant (str): One of filled, outlined (default), or standard.
    • 







Styling#


    

  • sx (dict): Component level styling API.
    • 

  • theme_config (dict): Theming API.
    • 

  • visual_size (str, default=”medium”): Controls the visual size/density of the multi-choice control. One of “small”, “medium”, or “large”.
    • 







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#


The MultiChoice widget allows selecting multiple values from a list of options:


multi_choice = pmui.MultiChoice(label='MultiChoice', value=['Apple', 'Pear'],
    options=['Apple', 'Banana', 'Pear', 'Strawberry'])

multi_choice







            
            
MultiChoice.value returns a list of the currently selected options:


multi_choice.value





['Apple', 'Pear']


The options parameter also accepts a dictionary whose keys are going to be the labels of the dropdown menu.


ages = pmui.MultiChoice(
    label='Ages', options={'Ten': 10, 'Twenty': 20, 'Thirty': 30}
)

ages







            
            
ages.value





[]


Updating the value will display the right label.


ages.value = [20, 30]









Filled and Standard Variants#


pmui.Row(
    pmui.MultiChoice(label='Fruits', value=['Apple', 'Pear'], options=['Apple', 'Banana', 'Pear', 'Strawberry'], variant="standard"),
    pmui.MultiChoice(label='Fruits', value=['Apple', 'Pear'], options=['Apple', 'Banana', 'Pear', 'Strawberry'], variant="filled")
)







            
            




Chips#


By default the selections are rendered as chips, this can be disabled with chip=False, alternatively the chip variant can be toggled with solid=False:


pmui.Row(
    pmui.MultiChoice(label='Fruits', value=['Apple', 'Pear'], options=['Apple', 'Banana', 'Pear', 'Strawberry'], chip=False),
    pmui.MultiChoice(label='Fruits', value=['Apple', 'Pear'], options=['Apple', 'Banana', 'Pear', 'Strawberry'], solid=False)
)







            
            




Colors#


pn.FlexBox(*[pmui.MultiChoice(
    label=color, value=['Apple', 'Pear'], options=['Apple', 'Banana', 'Pear', 'Strawberry'], color=color
) for color in pmui.Select.param.color.objects])







            
            




Visual Size#


Customize the visual size/density of the MultiChoice widget using the visual_size parameter:


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







            
            




Helper Text#


The helper_text parameter displays additional guidance text below the input field:


pmui.MultiChoice(label='Tags', options=['Python', 'JavaScript', 'Rust'], value=[], helper_text='Select one or more tags')







            
            




Disabled & Loading#


Like all widgets the MultiChoice supports disabled and loading states:


pmui.MultiChoice(label='Ages', options=['Ten', 'Twenty', 'Thirty'], disabled=True, loading=True)







            
            




Searchable#


You can make the MultiChoice widget searchable.


pmui.MultiChoice(label='Age', options=['Ten', 'Twenty', 'Thirty'], searchable=True)







            
            
You can configure whether options are filtered or merely highlighted on search.


pmui.Row(
    pmui.MultiChoice(label='Age', options=['Ten', 'Twenty', 'Thirty'], searchable=True, filter_on_search=True),
    pmui.MultiChoice(label='Age', options=['Ten', 'Twenty', 'Thirty'], searchable=True, filter_on_search=False)
)







            
            
You may provide a default string to filter on:


pmui.MultiChoice(label='Age', options=['Ten', 'Twenty', 'Thirty', 'Fourty', 'Fifty'], searchable=True, filter_str="F")







            
            





Disabled Options#


A subset of the displayed items can be disabled with disabled_options. The widget value cannot be set to one of the disabled_options, either programmatrically or with the user interface.


pmui.MultiChoice(label='Age', options=['Ten', 'Twenty', 'Thirty'], disabled_options=['Twenty'])







            
            




Bookmarks#


pmui.MultiChoice(label='Age', options=['Ten', 'Twenty', 'Thirty', 'Fourty', 'Fifty'], bookmarks=['Ten', 'Fourty'])







            
            




Icon Labels#


Material icon tokens like :material/zoom_out_map: render as icons in labels and option labels.


pmui.MultiChoice(
    label="Modes :material/zoom_out_map:",
    options={"Zoom :material/zoom_out_map:": "zoom", "Explore :material/explore:": "explore"},
    value=["zoom"],
)







            
            




API Reference#




Parameters#


The MultiChoice widget exposes a number of options which can be changed from both Python and Javascript. Try out the effect of these parameters interactively:


pmui.MultiChoice(label='Age', options=['Ten', 'Twenty', 'Thirty', 'Fourty', 'Fifty']).api(jslink=True)







            
            






References#


Panel Documentation:



Material UI Select:





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