Dashboard Layout

The dashboard layout component provides a customizable out-of-the-box layout for a typical dashboard page.

The DashboardLayout component is a quick, easy way to provide a standard full-screen layout with a header and sidebar to any dashboard page, as well as ready-to-use and easy to customize navigation and branding.

Many features of this component are configurable through the AppProvider component that must wrap it to provide the necessary context.

Demo

A DashboardLayout brings in a header and sidebar with navigation, as well as a scrollable area for page content.

If application themes are defined for both light and dark mode, a theme switcher in the header allows for easy switching between the two modes.

<AppProvider
  navigation={NAVIGATION}
  router={router}
  theme={demoTheme}
  window={demoWindow}
>
  <DashboardLayout>
    <DemoPageContent pathname={router.pathname} />
  </DashboardLayout>
</AppProvider>

<AppProvider
  navigation={NAVIGATION}
  router={router}
  theme={demoTheme}
  window={demoWindow}
>
  <DashboardLayout>
    <DemoPageContent pathname={router.pathname} />
  </DashboardLayout>
</AppProvider>

Press Enter to start editing

Branding

Some elements of the DashboardLayout can be configured to match your personalized brand.

This can be done via the branding prop in the AppProvider, which allows for setting a custom logo image or title text in the page header.

<AppProvider
  navigation={NAVIGATION}
  branding={{
    logo: <img src="https://mui.com/static/logo.png" alt="MUI logo" />,
    title: 'MUI',
  }}
  router={router}
  theme={demoTheme}
  window={demoWindow}
>
  <DashboardLayout>
    <DemoPageContent pathname={router.pathname} />
  </DashboardLayout>
</AppProvider>

<AppProvider
  navigation={NAVIGATION}
  branding={{
    logo: <img src="https://mui.com/static/logo.png" alt="MUI logo" />,
    title: 'MUI',
  }}
  router={router}
  theme={demoTheme}
  window={demoWindow}
>
  <DashboardLayout>
    <DemoPageContent pathname={router.pathname} />
  </DashboardLayout>
</AppProvider>

Press Enter to start editing

The navigation prop in the AppProvider allows for setting any type of navigation structure in the DashboardLayout sidebar by including different navigation elements as building blocks in any order.

The flexibility in composing and ordering these different elements allows for a great variety of navigation structures to fit your use case.

Navigation links can be placed in the sidebar as items with the format:

{ segment: 'home', title: 'Home', icon: <DescriptionIcon /> }

<AppProvider
  navigation={[
    {
      segment: 'home',
      title: 'Home',
      icon: <DescriptionIcon />,
    },
    {
      segment: 'about',
      title: 'About Us',
      icon: <DescriptionIcon />,
    },
  ]}
  router={router}
  theme={demoTheme}
  window={demoWindow}
>
  <DashboardLayout>
    <DemoPageContent pathname={router.pathname} />
  </DashboardLayout>
</AppProvider>

<AppProvider
  navigation={[
    {
      segment: 'home',
      title: 'Home',
      icon: <DescriptionIcon />,
    },
    {
      segment: 'about',
      title: 'About Us',
      icon: <DescriptionIcon />,
    },
  ]}
  router={router}
  theme={demoTheme}
  window={demoWindow}
>
  <DashboardLayout>
    <DemoPageContent pathname={router.pathname} />
  </DashboardLayout>
</AppProvider>

Press Enter to start editing

Navigation headings can be placed in the sidebar as items with the format:

{ kind: 'header', title: 'Animals' }

<AppProvider
  navigation={[
    {
      kind: 'header',
      title: 'Animals',
    },
    {
      segment: 'lion',
      title: 'Lion',
      icon: <DescriptionIcon />,
    },
    {
      kind: 'header',
      title: 'Movies',
    },
    {
      segment: 'lord-of-the-rings',
      title: 'Lord of the Rings',
      icon: <DescriptionIcon />,
    },
  ]}
  router={router}
  theme={demoTheme}
  window={demoWindow}
>
  <DashboardLayout>
    <DemoPageContent pathname={router.pathname} />
  </DashboardLayout>
</AppProvider>

<AppProvider
  navigation={[
    {
      kind: 'header',
      title: 'Animals',
    },
    {
      segment: 'lion',
      title: 'Lion',
      icon: <DescriptionIcon />,
    },
    {
      kind: 'header',
      title: 'Movies',
    },
    {
      segment: 'lord-of-the-rings',
      title: 'Lord of the Rings',
      icon: <DescriptionIcon />,
    },
  ]}
  router={router}
  theme={demoTheme}
  window={demoWindow}
>
  <DashboardLayout>
    <DemoPageContent pathname={router.pathname} />
  </DashboardLayout>
</AppProvider>

Press Enter to start editing

Dividers can can be placed between items in the sidebar as items with the format:

{
  kind: 'divider';
}

<AppProvider
  navigation={[
    {
      segment: 'star-wars',
      title: 'Star Wars',
      icon: <DescriptionIcon />,
    },
    { kind: 'divider' },
    {
      segment: 'eagle',
      title: 'Eagle',
      icon: <DescriptionIcon />,
    },
  ]}
  router={router}
  theme={demoTheme}
  window={demoWindow}
>
  <DashboardLayout>
    <DemoPageContent pathname={router.pathname} />
  </DashboardLayout>
</AppProvider>

<AppProvider
  navigation={[
    {
      segment: 'star-wars',
      title: 'Star Wars',
      icon: <DescriptionIcon />,
    },
    { kind: 'divider' },
    {
      segment: 'eagle',
      title: 'Eagle',
      icon: <DescriptionIcon />,
    },
  ]}
  router={router}
  theme={demoTheme}
  window={demoWindow}
>
  <DashboardLayout>
    <DemoPageContent pathname={router.pathname} />
  </DashboardLayout>
</AppProvider>

Press Enter to start editing

Nested navigation structures can be placed in the sidebar as items with the format:

{ title: 'Movies', icon: <FolderIcon />, children: [ ... ] }

<AppProvider
  navigation={[
    {
      segment: 'movies',
      title: 'Movies',
      icon: <FolderIcon />,
      children: [
        {
          segment: 'lord-of-the-rings',
          title: 'Lord of the Rings',
          icon: <DescriptionIcon />,
        },
        {
          segment: 'harry-potter',
          title: 'Harry Potter',
          icon: <DescriptionIcon />,
        },
      ],
    },
  ]}
  router={router}
  theme={demoTheme}
  window={demoWindow}
>
  <DashboardLayout>
    <DemoPageContent pathname={router.pathname} />
  </DashboardLayout>
</AppProvider>

<AppProvider
  navigation={[
    {
      segment: 'movies',
      title: 'Movies',
      icon: <FolderIcon />,
      children: [
        {
          segment: 'lord-of-the-rings',
          title: 'Lord of the Rings',
          icon: <DescriptionIcon />,
        },
        {
          segment: 'harry-potter',
          title: 'Harry Potter',
          icon: <DescriptionIcon />,
        },
      ],
    },
  ]}
  router={router}
  theme={demoTheme}
  window={demoWindow}
>
  <DashboardLayout>
    <DemoPageContent pathname={router.pathname} />
  </DashboardLayout>
</AppProvider>

Press Enter to start editing

Navigation links have an optional action prop to render any content on the right-side of the respective list item, such as badges with numbers, or buttons to toggle a popover menu.

<AppProvider
  navigation={[
    {
      segment: 'contacts',
      title: 'Contacts',
      icon: <PersonIcon />,
      action: <Chip label={7} color="primary" size="small" />,
    },
    {
      segment: 'calls',
      title: 'Calls',
      icon: <CallIcon />,
      action: popoverMenuAction,
      children: CALLS_NAVIGATION,
    },
  ]}
  router={router}
  theme={demoTheme}
  window={demoWindow}
>
  <DashboardLayout>
    <DemoPageContent pathname={router.pathname} />
  </DashboardLayout>
</AppProvider>

<AppProvider
  navigation={[
    {
      segment: 'contacts',
      title: 'Contacts',
      icon: <PersonIcon />,
      action: <Chip label={7} color="primary" size="small" />,
    },
    {
      segment: 'calls',
      title: 'Calls',
      icon: <CallIcon />,
      action: popoverMenuAction,
      children: CALLS_NAVIGATION,
    },
  ]}
  router={router}
  theme={demoTheme}
  window={demoWindow}
>
  <DashboardLayout>
    <DemoPageContent pathname={router.pathname} />
  </DashboardLayout>
</AppProvider>

Press Enter to start editing

Navigation links have an optional pattern prop to define a pattern to be matched for the item to be marked as selected. This feature is built on top of the path-to-regexp library. Some examples:

Constant path: orders
Dynamic segment: orders/:segment
Optional segment: orders{/:segment}?
One or more segments: orders{/:segment}+
Zero or more segments: orders{/:segment}*

<AppProvider
  navigation={[
    {
      segment: 'dashboard',
      title: 'Dashboard',
      icon: <DashboardIcon />,
    },
    {
      segment: 'orders',
      title: 'Orders',
      icon: <ShoppingCartIcon />,
      pattern: 'orders{/:orderId}*',
    },
  ]}
  router={router}
  theme={demoTheme}
  window={demoWindow}
>
  <DashboardLayout>
    <DemoPageContent pathname={router.pathname} navigate={router.navigate} />
  </DashboardLayout>
</AppProvider>

<AppProvider
  navigation={[
    {
      segment: 'dashboard',
      title: 'Dashboard',
      icon: <DashboardIcon />,
    },
    {
      segment: 'orders',
      title: 'Orders',
      icon: <ShoppingCartIcon />,
      pattern: 'orders{/:orderId}*',
    },
  ]}
  router={router}
  theme={demoTheme}
  window={demoWindow}
>
  <DashboardLayout>
    <DemoPageContent pathname={router.pathname} navigate={router.navigate} />
  </DashboardLayout>
</AppProvider>

Press Enter to start editing

The layout sidebar is collapsible to a mini-drawer (with icons only) in desktop and tablet viewports. This behavior can be disabled with the disableCollapsibleSidebar prop.

<DashboardLayout disableCollapsibleSidebar>
  <DemoPageContent pathname={router.pathname} />
</DashboardLayout>

<DashboardLayout disableCollapsibleSidebar>
  <DemoPageContent pathname={router.pathname} />
</DashboardLayout>

Press Enter to start editing

Start with mini-drawer on desktop

The layout sidebar can default to a collapsed mini-drawer on desktop viewport sizes with the defaultSidebarCollapsed prop.

<DashboardLayout defaultSidebarCollapsed>
  <DemoPageContent pathname={pathname} />
</DashboardLayout>

<DashboardLayout defaultSidebarCollapsed>
  <DemoPageContent pathname={pathname} />
</DashboardLayout>

Press Enter to start editing

The layout sidebar can be hidden if needed with the hideNavigation prop.

<DashboardLayout hideNavigation>
  <DemoPageContent pathname={router.pathname} />
</DashboardLayout>

<DashboardLayout hideNavigation>
  <DemoPageContent pathname={router.pathname} />
</DashboardLayout>

Press Enter to start editing

Full-size content

The layout content can take up the full available area with styles such as flex: 1 or height: 100%.

<DashboardLayout>
  <iframe
    title="Google Map"
    src="https://www.google.com/maps/embed?pb=!1m18!1m12!1m3!1d387190.2799181496!2d-74.25987571760744!3d40.69767006358627!2m3!1f0!2f0!3f0!3m2!1i1024!2i768!4f13.1!3m3!1m2!1s0x89c259af18b60165%3A0x8b621f8a7a7d28a4!2sNew%20York%2C%20NY%2C%20USA!5e0!3m2!1sen!2s!4v1633452834502!5m2!1sen!2s"
    style={{ flex: 1, border: 0 }}
    allowFullScreen
    loading="lazy"
  />
</DashboardLayout>

<DashboardLayout>
  <iframe
    title="Google Map"
    src="https://www.google.com/maps/embed?pb=!1m18!1m12!1m3!1d387190.2799181496!2d-74.25987571760744!3d40.69767006358627!2m3!1f0!2f0!3f0!3m2!1i1024!2i768!4f13.1!3m3!1m2!1s0x89c259af18b60165%3A0x8b621f8a7a7d28a4!2sNew%20York%2C%20NY%2C%20USA!5e0!3m2!1sen!2s!4v1633452834502!5m2!1sen!2s"
    style={{ flex: 1, border: 0 }}
    allowFullScreen
    loading="lazy"
  />
</DashboardLayout>

Press Enter to start editing

Account

The DashboardLayout comes integrated with the <Account /> component. It renders as an account management menu when a user is signed in – a session object is present – and a button when not.

<AppProvider
  session={session}
  authentication={authentication}
  navigation={NAVIGATION}
  router={router}
  theme={demoTheme}
  window={demoWindow}
>
  <DashboardLayout>
    <DemoPageContent pathname={router.pathname} />
  </DashboardLayout>
</AppProvider>

<AppProvider
  session={session}
  authentication={authentication}
  navigation={NAVIGATION}
  router={router}
  theme={demoTheme}
  window={demoWindow}
>
  <DashboardLayout>
    <DemoPageContent pathname={router.pathname} />
  </DashboardLayout>
</AppProvider>

Press Enter to start editing

Customization

Slots

Certain areas of the layout can be replaced with custom components by using the slots and slotProps props. Some possibly useful slots:

toolbarActions: allows you to add new items to the toolbar in the header, such as a search bar or button. The default ThemeSwitcher component can be imported and used if you wish to do so, as shown in the example below.
sidebarFooter: allows you to add footer content in the sidebar.

<DashboardLayout
  slots={{
    toolbarActions: ToolbarActionsSearch,
    sidebarFooter: SidebarFooter,
  }}
>
  <DemoPageContent pathname={router.pathname} />
</DashboardLayout>

<DashboardLayout
  slots={{
    toolbarActions: ToolbarActionsSearch,
    sidebarFooter: SidebarFooter,
  }}
>
  <DemoPageContent pathname={router.pathname} />
</DashboardLayout>

Press Enter to start editing

Examples

User account in layout sidebar

<DashboardLayout
  slots={{ toolbarAccount: () => null, sidebarFooter: SidebarFooterAccount }}
>
  <DemoPageContent pathname={pathname} />
</DashboardLayout>

<DashboardLayout
  slots={{ toolbarAccount: () => null, sidebarFooter: SidebarFooterAccount }}
>
  <DemoPageContent pathname={pathname} />
</DashboardLayout>

Press Enter to start editing

Settings menu with custom theme switcher

The useColorScheme hook can be used to create a custom theme switcher.

<DashboardLayout
  slots={{
    toolbarActions: CustomThemeSwitcher,
  }}
>
  <DemoPageContent pathname={router.pathname} />
</DashboardLayout>

<DashboardLayout
  slots={{
    toolbarActions: CustomThemeSwitcher,
  }}
>
  <DemoPageContent pathname={router.pathname} />
</DashboardLayout>

Press Enter to start editing

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

Dashboard Layout

Demo

Branding

Navigation

Navigation links

Navigation headings

Navigation dividers

Nested navigation

Navigation actions

Navigation pattern matching

Disable collapsible sidebar

Start with mini-drawer on desktop

Hide navigation

Full-size content

Account

Customization

Slots

Examples

User account in layout sidebar

Settings menu with custom theme switcher

API