--- layout: default title: "The MultiLevelMenu Component" --- # `` This [Enterprise Edition](https://react-admin-ee.marmelab.com)React Admin Enterprise Edition icon component adds support for nested sub menus in the left navigation bar. ![MultiLevelMenu](./img/multilevelmenu.png) When a React-admin application grows significantly, the default menu might not be the best solution. The `` can help unclutter the navigation: it renders a menu with an infinite number of levels and sub-menus. Menu Items that are not at the top level are rendered inside a collapsible panel. When a React-admin application grows significantly, [the default `` component](./Menu.md) might not be the best solution. The `` can help unclutter the navigation: it renders a menu with an infinite number of levels and sub menus. Menu Items that are not at the top level are rendered inside a collapsible panel. Test it live on [the Enterprise Edition Storybook](https://storybook.ra-enterprise.marmelab.com/?path=/story/ra-navigation-multilevelmenu--with-icons). ## Usage Create a custom Menu component using `` as root instead of ``. Menu entries should be ``, `` or `` components. They are very similar to the default `` from react-admin, except that they accept other `` (or `` or ``) as their children. For instance, here is how to create a menu with sub menus for each artist genre. The menu target is actually the same page - the artists list - but with a different filter: ```jsx import { MultiLevelMenu } from '@react-admin/ra-navigation'; import DashboardIcon from '@mui/icons-material/Dashboard'; import MusicIcon from '@mui/icons-material/MusicNote'; import PeopleIcon from '@mui/icons-material/People'; const MyMenu = () => ( } /> {/* The empty filter is required to avoid falling back to the previously set filter */} }> ); ``` Note that each `` requires a unique `name` attribute. Then, create a custom layout using [the `` component](./Layout.md) and pass your custom menu component to it. Make sure you wrap the layout with the `` component. ```jsx // in src/MyLayout.js import { Layout } from 'react-admin'; import { AppLocationContext } from '@react-admin/ra-navigation'; import { MyMenu } from './MyMenu'; export const MyLayout = ({ children }) => ( {children} ); ``` `` is necessary because `ra-navigation` doesn't use the URL to detect the current location. Instead, page components *declare* their location using a custom hook (`useDefineAppLocation()`). This allows complex site maps, with multiple levels of nesting. That's the reason why each `` requires a unique `name`, that matches a particular page location. You can set the `AppLocation` for a given page like so: ```jsx import { useDefineAppLocation } from '@react-admin/ra-navigation'; const ArtistRockList = () => { useDefineAppLocation('artists.rock'); return

Artist Rock List

; }; ``` And then use this `AppLocation` as `name` for ``: ```jsx ``` Check [the ra-navigation documentation](https://react-admin-ee.marmelab.com/documentation/ra-navigation) to learn more about App Location. Finally, pass this custom layout to the `` component ```jsx // in src/App.js import { Admin, Resource } from "react-admin"; import { MyLayout } from './MyLayout'; const App = () => ( // ... ); ``` ## Props | Prop | Required | Type | Default | Description | | -------------- | -------- | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | `children` | Optional | `ReactNode` | - | The Menu Items to be rendered. | | `initialOpen` | Optional | `boolean` | `false` | Whether the menu items with sub menus should be open initially. Has no effect if using the `categories` variant. | | `openItemList` | Optional | `string[]` | - | List of names of menu items that should be opened by default. | | `sx` | Optional | `SxProps` | - | Style overrides, powered by MUI System | Additional props are passed down to the root `
` component. ## `children` The menu items to render: ```jsx // in src/MyMenu.js import { MultiLevelMenu } from "@react-admin/ra-navigation"; import MusicIcon from '@mui/icons-material/MusicNote'; import PeopleIcon from '@mui/icons-material/People'; const MyMenu = () => ( } /> {/* The empty filter is required to avoid falling back to the previously set filter */} } > ); ``` Check [the `` section](#multilevelmenuitem) for more information. ## `initialOpen` Whether the menu items with sub menus should be open initially. Has no effect if using the `categories` variant. Defaults to `false`. ```jsx export const MyMenu = () => ( // ... ); ``` ## `openItemList` List of names of menu items that should be opened by default. If the menu item to be opened is nested, you have to fill in the name of all the parent items. Ex: `['artists', 'artists.rock', 'artists.rock.pop']` ```tsx import { MultiLevelMenu } from '@react-admin/ra-navigation'; const MyMenu = () => ( {/* The empty filter is required to avoid falling back to the previously set filter */} ); ``` ## `sx`: CSS API Pass an `sx` prop to customize the style of the main component and the underlying elements. {% raw %} ```jsx export const MyMenu = () => ( // ... ); ``` {% endraw %} To override the style of `` using the [application-wide style overrides](./AppTheme.md#theming-individual-components), use the `RaMenuRoot` key. Style overrides, powered by MUI System: | Rule name | Description | | --------------------------------------- | ----------------------------------------------------------------------------------------- | | `RaMultiLevelMenu` | Applied to the root `div` element | | `& .RaMultiLevelMenu-nav` | Applied to the `nav` element | | `& .RaMultiLevelMenu-navWithCategories` | Applied to the `nav` element when using the `categories` variant | | `& .RaMultiLevelMenu-list` | Applied to the MUI `` | ## `` The `` component displays a menu item with a label and an icon. ```jsx } /> ``` ### Usage ```tsx import { MultiLevelMenu } from '@react-admin/ra-navigation'; const MyMenu = () => ( {/* The empty filter is required to avoid falling back to the previously set filter */} ); ``` ### Props In addition to the props of react-router [``](https://reactrouter.com/web/api/NavLink) and those of material-ui [``](https://material-ui.com/api/list-item/). | Prop | Required | Type | Default | Description | | --------- | -------- | ----------- | ------- | ------------------------------------------------------------- | | `children`| Optional | `ReactNode` | | The sub-menu items to be rendered. | | `name` | Required | `string` | | The name of the item. Used to manage its open/closed state. | | `icon` | Optional | `ReactNode` | - | An icon element to display in front of the item. | | `label` | Optional | `string` | - | The label to display for this item. Accepts translation keys. | | `to` | Required | `string` | - | The location to link to. | | `sx` | Optional | `SxProps` | - | Style overrides, powered by MUI System. | Additional props are passed down to [the underling Material UI `` component](https://mui.com/api/list-item/#listitem-api). **Tip:** You can omit the `to` from `` property for `` elements that have a child menu item. ### `children` Pass a children to `` to define the sub-menu entries: ```jsx import { MultiLevelMenu } from "@react-admin/ra-navigation"; import PeopleIcon from '@mui/icons-material/People'; const MyMenu = () => ( } > ); ``` ### `name` The name of the item. Used to manage its open/closed state. ```tsx import { MultiLevelMenu } from '@react-admin/ra-navigation'; const MyMenu = () => ( ); ``` ### `icon` An icon element to display in front of the item. ```tsx import { MultiLevelMenu } from '@react-admin/ra-navigation'; import PeopleIcon from '@mui/icons-material/People'; const MyMenu = () => ( } /> ); ``` ### `label` The label to display for this item. Accepts translation keys. ```tsx import { MultiLevelMenu } from '@react-admin/ra-navigation'; import PeopleIcon from '@mui/icons-material/People'; const MyMenu = () => ( ); ``` ### `to` The location to go to for this item. Accepts a [path](./Routing.md#linking-to-a-page). ```tsx import { MultiLevelMenu } from '@react-admin/ra-navigation'; const MyMenu = () => ( ); ``` ### `sx` Style overrides, powered by MUI System: | Rule name | Description | | -------------------------------- | ---------------------------------------------------------------------------------- | | `RaMenuItem` | Applied to the root `div` element | | `& .RaMenuItem-container` | Applied to the MUI `` element | | `& .RaMenuItem-link` | Applied to the text of the `NavLink` | | `& .RaMenuItem-active` | Applied to the text of the `NavLink` when active (this item is the current page) | | `& .RaMenuItem-menuIcon` | Applied to the MUI `` element | | `& .RaMenuItem-icon` | Applied to the item icon element | | `& .RaMenuItem-button` | Applied to the MUI `` that open/closes the item children list | | `& .RaMenuItem-nestedList` | Applied to the MUI `` element that contains the item children | | `& .RaMenuItem-hiddenNestedList` | Applied to the MUI `` element that contains the item children when collapsed | | `& .RaMenuItem-itemButton` | Applied to the MUI `` | {% raw %} ```tsx import { MultiLevelMenu } from '@react-admin/ra-navigation'; const MyMenu = () => ( ); ``` {% endraw %} ## `` A `` for the dashboard. ### Usage ```tsx import { MultiLevelMenu } from '@react-admin/ra-navigation'; const MyMenu = () => ( ); ``` It accepts all props from [``](#multilevelmenuitem) ## `` A `` for resources. It only needs the `resource` name and automatically applies access control if your [`authProvider` implements `canAccess`](./Permissions.md#authprovidercanaccess) by calling it with the following parameters: ```js { resource: "posts", action: "list", } ``` ### Usage ```tsx import { MultiLevelMenu } from '@react-admin/ra-navigation'; const MyMenu = () => ( ); ``` ### Props In addition to the props of [``](#multilevelmenuitem), it accepts the following props | Prop | Required | Type | Default | Description | | ---------- | -------- | ----------- | ------- | --------------------------------- | | `resource` | Required | `string` | | The resource this item refers to. | **Tip:** Note that the `name` prop from [``](#multilevelmenuitem) is optional for ``. ### `resource` The resource this item refers to ```tsx import { MultiLevelMenu } from '@react-admin/ra-navigation'; const MyMenu = () => ( ); ``` ## Creating Menu Items For Resources If you want to render a custom menu item and the default resource menu items, use the `useResourceDefinitions` hook to retrieve the list of resources and create one menu item per resource. ```jsx // in src/MyMenu.js import { createElement } from 'react'; import { useResourceDefinitions } from 'react-admin'; import { MultiLevelMenu } from "@react-admin/ra-navigation"; import LabelIcon from '@mui/icons-material/Label'; export const MyMenu = () => { const resources = useResourceDefinitions(); return ( {Object.keys(resources).map(name => ( ))} } /> ); }; ```