App shell

AppShell draws a dashboard around a page: a sidebar, a navbar and a centred body. The admin area uses it, and so can an area of your own. This page is for module authors who build such an area. Set up the module first: Overview.

Use it in a layout

A layout reads its menus and passes them in. The Admin module's admin layout, simplified:

<AppShell
  id="admin"
  :title="t('title', 'Administration')"
  home="/admin"
  :navigation="navigation"
  :nav-label="t('nav.label', 'Admin navigation')"
  :search-groups="searchGroups"
  :back-to="{ to: '/', label: t('backToSite', 'Back to the site') }"
>
  <template #sidebar-footer="{ collapsed }">
    <AccountMenu block :collapsed="collapsed" />
  </template>
  <slot />
</AppShell>

Other props are icon?, title, navLabel, searchLabel? and backTo?: { to, label, icon? }. The slots are brand, sidebar-top and sidebar-footer (with { collapsed }), navbar-left, navbar-right and the default slot.

• id names the dashboard-sidebar-<id> cookie, which keeps the sidebar's width and collapse state. Give each area its own.
• home and backTo.to are raw paths. The shell adds the locale prefix.
• navigation is one UNavigationMenu list per group. A type: 'label' row heads a group.
• searchGroups adds the ⌘K button and palette. Leave it out for no search.
• wide makes the body full width instead of max-w-7xl. A page can ask with definePageMeta({ wide: true }).

What the shell does for you

• Navbar. It shows "title › active section". The document title defaults to the active section; a page's own useHead wins.
• Small screens. The navbar opens the sidebar as a drawer, which closes on navigation.
• Language. With more than one locale, the navbar shows the app's LanguageSelect, unless navbar-right is filled.
• Scrolling. The shell's panel scrolls, not the document, so hash links work inside it.
• Theme. The light app theme is utility classes on the shell root. Restyle an area through [data-area=app].

The rules for the area, such as one <h1> per page, are on Layouts and navigation.

Next steps

• Admin – use the shell through the ready-made admin area.
• Menu – read the menus a layout passes in as navigation.