MenuList#
Material version available
pn.ui.MenuList resolves to the Material Design implementation of this component,
documented in the panel-material-ui reference.
This page documents the classic pn.widgets.MenuList.
import panel as pn
import panel.ui
pn.extension()
The MenuList component is part of the Menu family of components. Menu components provide a structured way for users to navigate or choose between a series of defined items. In the case of MenuList, these items represent a series of menu options, which may also be nested in a tree.
Each item in the MenuList list is defined by a dictionary with several supported keys:
Item Structure#
Each item can include the following keys:
label(str, required): The text displayed for the breadcrumb item.href(str, optional): A URL to link to. If provided, the breadcrumb becomes a link.icon(str, optional): An icon to display next to the label.avatar(str, optional): An avatar or image to show beside the label.secondary(str, optional): The secondary text, e.g. for describing the item.color(str, optional): The color of the list item (optional)items(list[dict], optional): Nested items.actions(list, optional): Each menu item can have a list of actions associated with it which are accessible via a menu.selectable(boolean, optional): Whether this item can be selected.open(boolean, optional): Whether the menu item should be expanded by default (defaults toTrue).tooltip(str, optional): Tooltip text shown when hovering over the menu item.
These dictionaries are passed to the component via the items parameter as a list. When one of the items is selected it will be available on the value parameter.
Since only the allowed keys are synced with the frontend, other information can be stored in the item dictionaries.
Parameters:#
Core#
active(int | tuple[int, ...]): Index of the selected item (intif flat,tupleif nested).disabled(boolean): Whether the menu is disabled.expanded(list[int | tuple[int, ...]]): Indexes of expanded nodes.items(list[dict]): Menu items to select from.value(dict): The currently selected item.
Display#
color(str): The color variant indicating the selected list item, which must be one of'default'(white),'primary'(blue),'success'(green),'info'(yellow),'light'(light), or'danger'(red).dense(boolean): Whether to show the list items in a dense format, i.e. reduced margins.highlight(boolean): Whether to highlight the currently selected menu item.level_indent(int): Number of pixels each nested level is indented by.show_children(boolean): Whether to render child items nested under'items'.
Styling#
sx(dict): Component level styling API.theme_config(dict): Theming API.
Like all Menu-like components MenuList accepts a list of items, which each support sub-items:
items = [
{'label': 'Home', 'icon': 'home', 'secondary': 'Overview page'},
{'label': 'Gallery', 'icon': 'image', 'secondary': 'Visual overview'},
{'label': 'API', 'icon': 'code', 'secondary': 'API Reference'},
{'label': 'About', 'icon': 'info'},
]
menu_list = pn.ui.MenuList(items=items, active=3)
menu_list
Clicking on a particular item will highlight it and set both active and value parameters:
menu_list.active, menu_list.value
((3,), {'label': 'About', 'icon': 'info'})Nested Items#
Items may also contain sub-items making it possible to create a tree-like menu. You can also make items non-selectable and control the expanded state using the parameter. Much like active the expanded parameter represents a list of indexes to the selected items:
nested_list = pn.ui.MenuList(
items=[
{
'label': 'Home',
'icon': 'home',
'secondary': 'Overview page',
'items': [
{'label': 'Welcome', 'icon': 'handshake'},
{'label': 'Getting Started', 'icon': 'rocket'}
]
},
{
'label': 'Gallery',
'icon': 'image',
'secondary': 'Visual overview',
'selectable': False,
'items': [
{'label': 'Charts', 'icon': 'stacked_line_chart'},
{'label': 'Maps', 'icon': 'map'},
{'label': 'Animations', 'icon': 'animation'}
]
},
{
'label': 'API',
'icon': 'code',
'secondary': 'API Reference',
'items': [
{'label': 'Endpoints', 'icon': 'terminal'},
{'label': 'Schemas', 'icon': 'schema'}
]
},
{
'label': 'About',
'icon': 'info',
'items': [
{'label': 'Team', 'icon': 'groups'},
{'label': 'Contact', 'icon': 'mail'}
]
},
],
dense=True,
expanded=[0, 1]
)
nested_list
Actions#
MenuList items may also have a list of actions associated with it, which will be rendered into a menu:
actions = [
{'label': 'Favorite', 'icon': 'star', 'inline': True},
{'label': 'Edit', 'icon': 'edit'},
{'label': 'Delete', 'icon': 'delete'}
]
list_with_actions = pn.ui.MenuList(
items=[
{
'label': 'Notebook 1',
'icon': 'book',
'secondary': 'Last edited: Today',
'actions': actions
},
{
'label': 'Notebook 2',
'icon': 'book',
'secondary': 'Last edited: Yesterday',
'actions': actions
},
{
'label': 'Notebook 3',
'icon': 'book',
'secondary': 'Last edited: Last week',
'actions': actions
},
]
)
actions = pn.Column()
list_with_actions.on_action('Favorite', lambda item: actions.append(f"Favorited {item['label']}"))
list_with_actions.on_action('Edit', lambda item: actions.append(f"Edited {item['label']}"))
list_with_actions.on_action('Delete', lambda item: actions.append(f"Deleted {item['label']}"))
pn.ui.Row(list_with_actions, actions)
Toggle Actions#
Inline MenuList actions may also be defined as toggles, switching between True and False states. This can be enabled by setting toggle=True. In this mode a few additional configuration options become available for the action:
active_icon: The icon rendered when the toggle value is True.active_color: The color of theactive_iconwhen the toggle value is True.value: The current value of the toggle (True or False).
For example here we render a toggle to favorite various notebooks:
actions = [
{'label': 'Favorite', 'icon': 'star_outline', 'active_icon': 'star', 'color': 'warning', 'inline': True, 'toggle': True, 'value': False},
]
list_with_toggle_action = pn.ui.MenuList(
items=[
{
'label': 'Notebook 1',
'icon': 'book',
'actions': actions
},
{
'label': 'Notebook 2',
'icon': 'book',
'actions': actions
},
{
'label': 'Notebook 3',
'icon': 'book',
'actions': actions
},
]
)
toggle_actions = pn.Column()
list_with_toggle_action.on_action('Favorite', lambda item: toggle_actions.append(f'{item["label"]}: {item["actions"][0]["value"]}'))
pn.Row(list_with_toggle_action, toggle_actions)
The True/False state of the toggle will be updated on the “value” key of the actions:
list_with_toggle_action.items
[{'label': 'Notebook 1', 'icon': 'book', 'actions': [{'label': 'Favorite', 'icon': 'star_outline', 'active_icon': 'star', 'color': 'warning', 'inline': True, 'toggle': True, 'value': False}]}, {'label': 'Notebook 2', 'icon': 'book', 'actions': [{'label': 'Favorite', 'icon': 'star_outline', 'active_icon': 'star', 'color': 'warning', 'inline': True, 'toggle': True, 'value': False}]}, {'label': 'Notebook 3', 'icon': 'book', 'actions': [{'label': 'Favorite', 'icon': 'star_outline', 'active_icon': 'star', 'color': 'warning', 'inline': True, 'toggle': True, 'value': False}]}]Display Options#
collapsed#
The collapsed parameter allows toggling between a view showing just the icons to the expanded view:
collapsed = pn.ui.Switch(label='Collapsed', value=True)
pn.ui.Column(collapsed, pn.ui.MenuList(items=items, active=2, collapsed=collapsed))
color#
MenuList supports different colors to indicate which item is selected:
pn.GridBox(*(
menu_list.clone(color=color, label=color, active=0, highlight=True)
for color in pn.ui.MenuList.param.color.objects
), ncols=5)
highlight#
Highlighting can be disabled entirely by setting highlight=False:
pn.ui.MenuList(items=items, highlight=False, active=2)
Icon Labels#
Material icon tokens like :material/zoom_out_map: render as icons in labels and option labels.
items = [
{"label": ":material/zoom_out_map: Overview"},
{"label": ":material/zoom_out_map: Details"},
]
pn.ui.MenuList(label=":material/zoom_out_map: Sections", items=items, active=0)
API Reference#
Parameters#
The MenuList exposes a number of options which can be changed from both Python and Javascript. Try out the effect of these parameters interactively:
pn.ui.MenuList(items=[
{'label': 'Open', 'icon': 'description'},
{'label': 'Save', 'icon': 'save'},
{'label': 'Exit', 'icon': 'close'},
], label='File').api(jslink=True)
References#
Panel Documentation:
How-to guides on interactivity - Learn how to add interactivity to your applications using widgets
Setting up callbacks and links - Connect parameters between components and create reactive interfaces
Declarative UIs with Param - Build parameter-driven applications
Material UI Button:
Material UI Button Reference - Complete documentation for the underlying Material UI component
Material UI Button API - Detailed API reference and configuration options
Material UI Menu:
Material UI Menu Reference - Complete documentation for the underlying Material UI component
Material UI Menu API - Detailed API reference and configuration options
