Document List component

[MarcSkovMadsen]

The List component is not documented.

I need a menu for #143 and also in general in holoviz/panel#1862 so I started creating my own (see below custom code) before discovering the existing List componenent. When documenting the List component please

• make it clear whether it can be used liked a navigation menu or not.
• consider whether the api is the right one. The List widget is a bit like a Select or RadioButtonGroup widget. Should it be possible to use as a drop in replacement? Right now it cannot for example because the parameter name items is used instead of options.

---

Custom Code

import panel as pn
from panel.custom import ReactComponent
import param
from panel_material_ui.base import COLORS

pn.extension()

class Menu(ReactComponent):
    value = param.String()
    options = param.List()
    
    _importmap = {
        "imports": {
            "@mui/material": "https://esm.sh/@mui/material",
            "@mui/icons-material": "https://esm.sh/@mui/icons-material",
        }
    }

    _esm = """
    import List from '@mui/material/List';
    import ListItemButton from '@mui/material/ListItemButton';
    import ListItemIcon from '@mui/material/ListItemIcon';
    import ListItemText from '@mui/material/ListItemText';
    import * as Icons from '@mui/icons-material';

    const SidebarMenu = (menuItems, value, setValue) => (
    <List dense component="nav">
        {menuItems.map(({ title, icon, href, divider }) => {
            const IconComponent = Icons[icon];
            return (
                <ListItemButton component="a" href={href} key={title} selected={title === value} divider={ divider } onClick={ () => { setValue(title) } } >
                    <ListItemIcon>{IconComponent ? <IconComponent /> : null}</ListItemIcon>
                    <ListItemText primary={title} />
                </ListItemButton>
            );
            })
        }
    </List>
    );

    export function render({ model }) {
      const [options ] = model.useState("options")
      const [value, setValue] = model.useState("value")
      
      return SidebarMenu(options, value, setValue )
    }
    """

menu_items = [
    { "title": 'Dashboard', "icon": 'Dashboard', "href": '/dashboard', "divider": True },
    { "title": 'Tables', "icon": 'TableChart', "divider": False },
    { "title": 'Notifications', "icon": 'Notifications'},
]
value = "Dashboard"

timeline = Menu(width=500, styles={"border": "1px solid black"}, options=menu_items, value=value)

pn.Column(timeline, timeline.param.value).servable()

[MarcSkovMadsen]

After adding the href property in #165 I'm able to create a link menu using the code

custom-menu.mp4

import panel as pn
from panel.custom import ReactComponent
import param
from panel_material_ui.base import COLORS
from panel_material_ui.widgets import List

pn.extension()

List(
    name="Menu",
    items={
    "Github": { "label": 'GitHub', "icon": 'code', "href": 'https://github.com/panel-extensions/panel-material-ui'},
    "Discourse": { "label": 'Discourse', "icon": 'people', "href": "https://discourse.holoviz.org/" },
    "Discord": { "label": 'Discord', "icon": 'chat'},
}, sx={
    '& .MuiListItemButton-root': {
        "border-radius": "var( --mui-shape-borderRadius )",
        "height": "40px",
    },
    '& .MuiListItemButton-root:hover': {
        'bgcolor': 'black',
        'color': 'white',
        '& .MuiListItemIcon-root': {
            'color': 'white',
        },
    }
}, width=300).servable()

The only thing missing is the ability to set the selected property.

[philippjfr]

consider whether the api is the right one. The List widget is a bit like a Select or RadioButtonGroup widget. Should it be possible to use as a drop in replacement? Right now it cannot for example because the parameter name items is used instead of options.

I did consider that but decided that a new Menu API is the correct choice here. Options were persistent selections between a number of options, while the Menu components are more complex, the selections are not necessarily persistent, i.e. in many scenarios they are more like buttons, i.e. invoking transient actions, than they are like selections. The navigation use case is more like Select API where the selection persists, but the fact that the items are more complex than the simpler options still makes me quite certain that the distinct Menu API is the correct one.