List#

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

import panel as pn
import panel_material_ui as pmui

pn.extension()

The List 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 List, these items represent a series of menu options, which may also be nested in a tree.

Each item in the List 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.

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 (boolean): Whether the dialog is visible.
disabled (boolean): Whether the menu is disabled.
items (list[dict]): Menu items to select from.
value (dict): The currently selected item.

Display#

color (str): The color of the selected list item, one of ‘default’, ‘primary’, ‘secondary’, ‘success’, ‘info’, ‘warning’, ‘danger’, ‘light’ or ‘dark’.
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.

Styling#

sx (dict): Component level styling API.
theme_config (dict): Theming API.

list_menu = pmui.List(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'},
], active=3)

list_menu

Clicking on a particular item will highlight it and set both active and value parameters:

list_menu.value

{'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

list_menu = pmui.List(
    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,
)

list_menu

Actions#

List items may also have a list of actions associated with it, which will be rendered into a menu:

actions = [
    {'label': 'Edit', 'icon': 'edit'},
    {'label': 'Delete', 'icon': 'delete'}
]

list_with_actions = pmui.List(
    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('Edit', lambda item: actions.append(f"Edited {item['label']}"))
list_with_actions.on_action('Delete', lambda item: actions.append(f"Deleted {item['label']}"))

pn.Row(list_with_actions, actions)

Display Options#

`color`#

pn.GridBox(*(
    list_menu.clone(color=color, label=color, active=0)
    for color in pmui.List.param.color.objects
), ncols=2)

Controls#

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

pn.Row(list_menu.controls(jslink=True), list_menu)