App

Storybook GitHub

<script setup lang="ts">
import MtApp from "@shopware-ag/meteor-component-library/MtApp";
import MtText from "@shopware-ag/meteor-component-library/MtText";
</script>

<template>
  <mt-app class="app-example" :mobile-breakpoint="0">
    <template #header>
      <div class="slot slot--header">
        <mt-text size="xs" color="color-text-secondary-default">header</mt-text>
      </div>
    </template>

    <template #sidebar-start>
      <div class="slot slot--sidebar-start">
        <mt-text size="xs" color="color-text-secondary-default">
          sidebar-start
        </mt-text>
      </div>
    </template>

    <template #content>
      <div class="slot slot--content">
        <mt-text size="xs" color="color-text-secondary-default">content</mt-text>
      </div>
    </template>

    <template #sidebar-end>
      <div class="slot slot--sidebar-end">
        <mt-text size="xs" color="color-text-secondary-default">
          sidebar-end
        </mt-text>
      </div>
    </template>
  </mt-app>
</template>

<style scoped>
.app-example {
  --mt-app-height: 360px;

  border-radius: var(--border-radius-m);
}

.slot {
  display: grid;
  place-items: center;
  box-sizing: border-box;
  height: 100%;
  background-color: var(--color-background-secondary-default);
  border: 1px dashed var(--color-border-primary-default);
  border-radius: var(--border-radius-m);
}

.slot--header {
  height: var(--scale-size-56);
  margin: var(--scale-size-8);
}

.slot--sidebar-start {
  width: var(--scale-size-160);
}

.slot--sidebar-end {
  width: var(--scale-size-192);
}

.slot--content {
  min-height: calc(100% - var(--scale-size-32));
  margin: var(--scale-size-16);
}
</style>

Usage

App is the root of a standalone Meteor application: it fills the viewport, lays out the header, both sidebars and the content, and turns the sidebars into drawers on small screens. It also provides the theme, future flags and the Snackbar host, while routing, navigation and page content stay yours.

import { MtApp, useMtApp } from "@shopware-ag/meteor-component-library";

Examples

Application setup

Fill the slots you need and render your router view in content. Empty slots leave no region behind.

<script setup lang="ts">
import MtApp from "@shopware-ag/meteor-component-library/MtApp";
import MtText from "@shopware-ag/meteor-component-library/MtText";
</script>

<template>
  <mt-app>
    <template #header>
      <mt-text as="span" size="s" weight="bold">Meteor Shop</mt-text>
    </template>

    <template #sidebar-start>
      <nav aria-label="Main">
        <router-link to="/">Dashboard</router-link>
        <router-link to="/orders">Orders</router-link>
      </nav>
    </template>

    <template #content>
      <router-view />
    </template>

    <template #sidebar-end>
      <section aria-label="Assistant">
        <mt-text size="xs">Assistant</mt-text>
      </section>
    </template>
  </mt-app>
</template>

Regions

Every slot is optional. Absent or empty regions leave neither an element nor a gap behind, and the remaining regions take the space.

<script setup lang="ts">
import { ref } from "vue";
import MtApp from "@shopware-ag/meteor-component-library/MtApp";
import MtSwitch from "@shopware-ag/meteor-component-library/MtSwitch";
import MtText from "@shopware-ag/meteor-component-library/MtText";

const showHeader = ref(true);
const showStart = ref(true);
const showEnd = ref(false);
</script>

<template>
  <div class="app-regions">
    <div class="app-regions__controls">
      <mt-switch v-model="showHeader" label="Header" />
      <mt-switch v-model="showStart" label="Start sidebar" />
      <mt-switch v-model="showEnd" label="End sidebar" />
    </div>

    <mt-app class="app-regions__shell" :mobile-breakpoint="0">
      <template v-if="showHeader" #header>
        <div class="slot slot--header">
          <mt-text size="xs" color="color-text-secondary-default">header</mt-text>
        </div>
      </template>

      <template v-if="showStart" #sidebar-start>
        <div class="slot slot--sidebar">
          <mt-text size="xs" color="color-text-secondary-default">
            sidebar-start
          </mt-text>
        </div>
      </template>

      <template #content>
        <div class="slot slot--content">
          <mt-text size="xs" color="color-text-secondary-default">content</mt-text>
        </div>
      </template>

      <template v-if="showEnd" #sidebar-end>
        <div class="slot slot--sidebar">
          <mt-text size="xs" color="color-text-secondary-default">
            sidebar-end
          </mt-text>
        </div>
      </template>
    </mt-app>
  </div>
</template>

<style scoped>
.app-regions {
  display: grid;
  gap: var(--scale-size-16);
  width: 100%;
}

.app-regions__controls {
  display: flex;
  flex-wrap: wrap;
  gap: var(--scale-size-16);
}

.app-regions__shell {
  --mt-app-height: 280px;

  border-radius: var(--border-radius-m);
}

.slot {
  display: grid;
  place-items: center;
  box-sizing: border-box;
  height: 100%;
  background-color: var(--color-background-secondary-default);
  border: 1px dashed var(--color-border-primary-default);
  border-radius: var(--border-radius-m);
}

.slot--header {
  height: var(--scale-size-56);
  margin: var(--scale-size-8);
}

.slot--sidebar {
  width: var(--scale-size-160);
}

.slot--content {
  min-height: calc(100% - var(--scale-size-32));
  margin: var(--scale-size-16);
}
</style>

Theme

The shell applies the stored theme preference. Change it from any component inside the shell with useTheme, for example together with Theme Select.

<script setup lang="ts">
import MtThemeSelect from "@shopware-ag/meteor-component-library/MtThemeSelect";
import { useTheme } from "@shopware-ag/meteor-component-library";

const { theme } = useTheme();
</script>

<template>
  <mt-theme-select v-model="theme" label="Color theme" />
</template>

Fullscreen views

A view hides the header and sidebars with useMtAppRegions, for example a route with a fullscreen editor. The regions return when the view unmounts.

<script setup lang="ts">
import { defineComponent, h, ref } from "vue";
import MtApp from "@shopware-ag/meteor-component-library/MtApp";
import MtSwitch from "@shopware-ag/meteor-component-library/MtSwitch";
import MtText from "@shopware-ag/meteor-component-library/MtText";
import { useMtAppRegions } from "@shopware-ag/meteor-component-library";

const FullscreenView = defineComponent({
  setup() {
    const fullscreen = ref(false);

    useMtAppRegions(() => ({
      header: !fullscreen.value,
      sidebarStart: !fullscreen.value,
      sidebarEnd: !fullscreen.value,
    }));

    return () =>
      h(MtSwitch, {
        label: "Fullscreen view",
        modelValue: fullscreen.value,
        "onUpdate:modelValue": (value: boolean) => {
          fullscreen.value = value;
        },
      });
  },
});
</script>

<template>
  <mt-app class="app-fullscreen" :mobile-breakpoint="0">
    <template #header>
      <div class="slot slot--header">
        <mt-text size="xs" color="color-text-secondary-default">header</mt-text>
      </div>
    </template>

    <template #sidebar-start>
      <div class="slot slot--sidebar">
        <mt-text size="xs" color="color-text-secondary-default">
          sidebar-start
        </mt-text>
      </div>
    </template>

    <template #content>
      <div class="slot slot--content">
        <mt-text size="xs" color="color-text-secondary-default">content</mt-text>
        <fullscreen-view />
      </div>
    </template>

    <template #sidebar-end>
      <div class="slot slot--sidebar">
        <mt-text size="xs" color="color-text-secondary-default">
          sidebar-end
        </mt-text>
      </div>
    </template>
  </mt-app>
</template>

<style scoped>
.app-fullscreen {
  --mt-app-height: 280px;

  border-radius: var(--border-radius-m);
}

.slot {
  display: grid;
  place-items: center;
  box-sizing: border-box;
  height: 100%;
  background-color: var(--color-background-secondary-default);
  border: 1px dashed var(--color-border-primary-default);
  border-radius: var(--border-radius-m);
}

.slot--header {
  height: var(--scale-size-56);
  margin: var(--scale-size-8);
}

.slot--sidebar {
  width: var(--scale-size-160);
}

.slot--content {
  place-content: center;
  gap: var(--scale-size-16);
  min-height: calc(100% - var(--scale-size-32));
  margin: var(--scale-size-16);
}
</style>

Reading the shell state

useMtApp() gives descendants read access to the layout mode, the open drawer and the theme, plus openDrawer, closeDrawer and setTheme.

<script setup lang="ts">
import { defineComponent, h } from "vue";
import MtApp from "@shopware-ag/meteor-component-library/MtApp";
import MtText from "@shopware-ag/meteor-component-library/MtText";
import { useMtApp } from "@shopware-ag/meteor-component-library";

const ShellState = defineComponent({
  setup() {
    const app = useMtApp();

    return () =>
      h(MtText, { size: "xs" }, () => [
        `Layout: ${app.isMobile.value ? "mobile" : "desktop"} · `,
        `Drawer: ${app.activeDrawer.value ?? "none"} · `,
        `Theme: ${app.theme.value} (${app.resolvedTheme.value})`,
      ]);
  },
});
</script>

<template>
  <mt-app class="app-composable" :mobile-breakpoint="0">
    <template #content>
      <div class="app-composable__content">
        <shell-state />
      </div>
    </template>
  </mt-app>
</template>

<style scoped>
.app-composable {
  --mt-app-height: 160px;

  border-radius: var(--border-radius-m);
}

.app-composable__content {
  padding: var(--scale-size-24);
}
</style>

Anatomy

header: spans the full width, keeps its intrinsic height and sits directly on the row of sidebars and content; without a header that row keeps an 8px gap to the top edge. In the mobile layout the shell places a trigger for every filled sidebar at the start and end of it. Without header content, a minimal shell-owned header holds just the triggers.
sidebar-start and sidebar-end: complementary landmarks in the desktop layout. Below the mobile breakpoint their content moves into a Drawer without being re-mounted, so component and form state inside them survive every layout change. Each drawer has a close button, a backdrop, Escape and swipe handling and its own translated accessible name. The drawers use the floating look of Drawer.
content: the <main> landmark and the only scroll container of the shell, available as scrollContainer from useMtApp().
global: app-wide hosts that render no layout box, such as notification renderers or keyboard-shortcut listeners. They stay mounted across route changes.

API reference

Props

Prop	Type	Default
`future` Future flags for every Meteor component inside the shell. All flags, including upcoming ones, are enabled by default; the given flags override that, e.g. `{ removeCardWidth: false }` keeps every other flag enabled and `{ all: false }` disables all of them.	`any`	`undefined`
`mobile-breakpoint` The viewport width in pixels below which the shell switches to the mobile layout and the sidebars become off-canvas drawers. `0` disables the mobile layout.	`number`	`1280`

Slots

Slot	Bindings
`header` The header bar. In the mobile layout the drawer triggers are placed at its start and end.	`{ isMobile: boolean; }`
`sidebar-start` The start sidebar, usually the navigation. Becomes a drawer in the mobile layout.	`SidebarSlotProps`
`content` The scrollable main content.	`any`
`sidebar-end` The end sidebar, for example an assistant or contextual tools. Becomes a drawer in the mobile layout.	`SidebarSlotProps`
`global` App-wide hosts without a layout box, such as keyboard shortcut listeners.	`any`

Exposed

Name	Type
`openDrawer` Opens the drawer of the given side (mobile layout only).	`(side: MtAppSide) => void`
`closeDrawer` Closes the open drawer.	`() => void`

Best practices

Mount App once, as the root of a standalone application, directly below <body> or untransformed wrappers.
Hide regions for a single view with useMtAppRegions instead of removing slot content from the root component.
Render your router view inside the content slot and keep page padding inside your pages.
Rely on the future flags App enables by default, and opt out of single flags through future only when a change does not fit your application yet.

Don't

Do not render more than one App in an application, not even in separate subtrees.
Do not use the shell inside Administration extensions, iframes or existing page layouts; keep the Theme Provider and your host's layout there.
Do not mount your own Snackbar host; the shell already renders one, and an additional host stays silent.
Do not render another <main> element inside the content slot.
Do not give your own content inside the shell a z-index at or above --z-index-drawer (900); it would cover the drawers.

Behavior

Mobile breakpoint. Below mobileBreakpoint (1280px by default) the shell switches to the mobile layout, marked with data-layout="mobile" on its root. A value of 0 disables the mobile layout.
Height. The shell is 100dvh tall (with a 100vh fallback). Override it with the --mt-app-height custom property.
Drawers. At most one drawer is open. Opening the other side closes the first one, and leaving the mobile layout closes any open drawer and removes all modal state.
Scrolling. Only the content panel scrolls. While the shell is mounted the document itself never scrolls and the page behind the shell takes the shell background, so an overlay positioned below the fold cannot push the page around. The lock is plain CSS and works before hydration. While a drawer is open the backdrop covers the content, so its scroll position stays untouched without any scroll lock.
Routing. When the application uses Vue Router, the shell picks it up on its own: every navigation closes an open drawer, a navigation to another path scrolls the content to the top, back and forward restore the scroll position of the content for that history entry, and a URL hash scrolls its target into view. The router's scrollBehavior has no effect, because the window never scrolls. With another router, call closeDrawer() and scroll scrollContainer from useMtApp yourself.
Hidden regions. Views hide the header and sidebars with useMtAppRegions. Hidden regions stay mounted, lose their drawer trigger, and come back when the last view that hides them unmounts.
Printing. The printout leaves out the header, the sidebars and the backdrop, and prints the content in its full length instead of the visible part of the scroll panel.
Future flags. All future flags are enabled by default, including the ones added in later releases, so the shell always previews the next major. future applies on top of that: { removeCardWidth: false } opts out of a single flag and keeps all others, { all: false } opts out of all of them, and { all: false, removeCardWidth: true } enables a single one.
Theme. The shell reads the preference from localStorage (mt-theme, system by default), writes the resolved theme to <html data-theme> and follows changes made through useTheme or setTheme from useMtApp.
One shell. The drawers, the snackbar host, the document lock and the router integration expect a single App per application.

Server-side rendering

The shell renders on the server and hydrates without mismatches. The server knows neither the viewport nor the stored theme, which leads to these differences until the page hydrates:

Below 1280px the sidebars stay hidden, then the mobile layout with its drawer triggers appears. A custom mobileBreakpoint only applies after hydration.
Regions that a route hides with useMtAppRegions still show.
The persisted theme applies after hydration. To avoid a flash of the wrong theme, apply it with an inline script in <head> that runs before the page paints:

<script>
  (function () {
    var theme = localStorage.getItem("mt-theme");
    if (theme !== "light" && theme !== "dark") {
      theme = matchMedia("(prefers-color-scheme: dark)").matches
        ? "dark"
        : "light";
    }
    document.documentElement.dataset.theme = theme;
  })();
</script>

Layering

Overlays keep their render targets and stack in this order. Each layer reads its z-index from a custom property on :root, set by the global stylesheet, so an application can move a whole layer. Without the global stylesheet the defaults apply.

Layer	Custom property	Default	Rendered in
Header, sidebars, content		document order	shell
Drawer backdrop and drawers	`--z-index-drawer`	900	body
Modal	`--z-index-modal`	1000	body
Popover, context buttons	`--z-index-popover`	1070	body
Tooltip	`--z-index-tooltip`	1100	body
Select result lists		1100	body
Action Menu	`--z-index-menu`	1300	body
Snackbar	`--z-index-notification`	1600	body
Date picker		99999	body

Drawers and modals share one modal layer. While one is open everything behind it is inert, and overlays opened from inside it, such as menus, popovers, select result lists, date pickers and snackbars, stay usable. A modal opened from a drawer stacks above it. Escape closes the innermost layer only: an open select result list or tooltip first, then the modal, then the drawer.

Accessibility

The shell renders header, main and two complementary landmarks with translated names ("Primary sidebar" and "Secondary sidebar").
A translated "Skip to content" button is the first focusable element. It stays visually hidden until it receives focus and moves the focus to the content, so keyboard users can scroll the content right away.
Drawer triggers carry aria-expanded and aria-controls. An open drawer is a modal dialog: the focus moves into it, Tab and Shift+Tab stay inside, the rest of the page becomes inert, and Escape, the close button or the backdrop close it and return the focus to the trigger.
Closed drawers are unreachable for keyboard and assistive technology. When a region is hidden while it holds the focus, the focus moves to the content.
The slide animation is skipped when the user prefers reduced motion.

Drawer: when a panel should slide in on demand, independent of the shell's sidebars.
Theme Provider: when a Meteor view is embedded, for example in an Administration extension, and only needs future flags.
Container: when page content inside the shell should keep a readable maximum width.
Theme Select: when users should pick the theme the shell applies.

Edit this pageorReport an issue

Action Menu

A trigger-revealed list of contextual actions for a specific object or view.

Avatar

A compact visual representation of a person or entity, shown as a profile image or initials.