App

Storybook GitHub

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

const navigation = ["Dashboard", "Orders", "Customers", "Products", "Settings"];
</script>

<template>
  <mt-app
    class="app-example"
    :mobile-breakpoint="0"
    :apply-theme="false"
    :lock-document="false"
  >
    <template #header>
      <div class="app-example__header">
        <mt-text as="span" size="s" weight="bold">Meteor Shop</mt-text>
        <mt-button variant="secondary" size="small">Jane Doe</mt-button>
      </div>
    </template>

    <template #sidebar-start>
      <nav class="app-example__nav" aria-label="Main">
        <a v-for="entry in navigation" :key="entry" href="#" @click.prevent>{{
          entry
        }}</a>
      </nav>
    </template>

    <template #content>
      <div class="app-example__content">
        <mt-card title="Orders" subtitle="Today">
          <mt-text size="xs"
            >The content region scrolls on its own; the shell never
            does.</mt-text
          >
        </mt-card>
      </div>
    </template>

    <template #sidebar-end>
      <div class="app-example__details">
        <mt-text as="h2" size="s" weight="semibold">Details</mt-text>
        <mt-text size="xs">Contextual tools for the current page.</mt-text>
      </div>
    </template>
  </mt-app>
</template>

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

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

.app-example__header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  min-height: var(--scale-size-48);
  padding-inline: var(--scale-size-16);
}

.app-example__nav {
  display: grid;
  gap: var(--scale-size-4);
  width: var(--scale-size-192);
  padding: var(--scale-size-16);
}

.app-example__nav a {
  padding: var(--scale-size-8);
  border-radius: var(--border-radius-xs);
  color: var(--color-text-primary-default);
  font-size: var(--font-size-xs);
  text-decoration: none;
}

.app-example__content {
  padding: var(--scale-size-24);
}

.app-example__details {
  display: grid;
  gap: var(--scale-size-8);
  width: var(--scale-size-224);
  padding: 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"
      :apply-theme="false"
      :lock-document="false"
    >
      <template v-if="showHeader" #header>
        <div class="app-regions__region">
          <mt-text as="span" size="xs" weight="semibold">Header</mt-text>
        </div>
      </template>

      <template v-if="showStart" #sidebar-start>
        <div class="app-regions__region app-regions__sidebar">
          <mt-text as="span" size="xs" weight="semibold">Start sidebar</mt-text>
        </div>
      </template>

      <template #content>
        <div class="app-regions__region">
          <mt-text size="xs">
            Sidebars and content sit directly below the header, with 8px between
            them and towards the shell edges. Without a header, that spacing
            applies at the top too. Absent regions leave no gap behind.
          </mt-text>
        </div>
      </template>

      <template v-if="showEnd" #sidebar-end>
        <div class="app-regions__region app-regions__sidebar">
          <mt-text as="span" size="xs" weight="semibold">End sidebar</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);
}

.app-regions__region {
  padding: var(--scale-size-16);
}

.app-regions__sidebar {
  width: var(--scale-size-160);
}
</style>

Overlays and layering

Header dropdowns, modals and snackbars render above the content. The shell mounts the snackbar host itself, so useSnackbar() works anywhere below it.

<script setup lang="ts">
import MtApp from "@shopware-ag/meteor-component-library/MtApp";
import MtButton from "@shopware-ag/meteor-component-library/MtButton";
import MtModal from "@shopware-ag/meteor-component-library/MtModal";
import MtModalRoot from "@shopware-ag/meteor-component-library/MtModalRoot";
import MtModalTrigger from "@shopware-ag/meteor-component-library/MtModalTrigger";
import MtPopover from "@shopware-ag/meteor-component-library/MtPopover";
import MtPopoverItem from "@shopware-ag/meteor-component-library/MtPopoverItem";
import MtText from "@shopware-ag/meteor-component-library/MtText";
import { useSnackbar } from "@shopware-ag/meteor-component-library";

const { addSnackbar } = useSnackbar();
</script>

<template>
  <mt-app
    class="app-overlays"
    :mobile-breakpoint="0"
    :apply-theme="false"
    :lock-document="false"
  >
    <template #header>
      <div class="app-overlays__header">
        <mt-text as="span" size="s" weight="bold">Meteor Shop</mt-text>

        <mt-popover title="Account">
          <template #trigger="{ toggleFloatingUi }">
            <mt-button
              variant="secondary"
              size="small"
              @click.stop="toggleFloatingUi"
            >
              Jane Doe
            </mt-button>
          </template>

          <template #popover-items__base>
            <mt-popover-item label="Profile" />
            <mt-popover-item label="Sign out" type="critical" />
          </template>
        </mt-popover>
      </div>
    </template>

    <template #content>
      <div class="app-overlays__content">
        <mt-button
          variant="primary"
          size="small"
          @click="addSnackbar({ message: 'Order saved', variant: 'success' })"
        >
          Show snackbar
        </mt-button>

        <mt-modal-root>
          <mt-modal-trigger :as="MtButton" variant="secondary" size="small">
            Open modal
          </mt-modal-trigger>

          <mt-modal title="Delete order">
            <mt-text size="xs">This action cannot be undone.</mt-text>

            <template #footer>
              <mt-button variant="critical" size="small">Delete</mt-button>
            </template>
          </mt-modal>
        </mt-modal-root>
      </div>
    </template>
  </mt-app>
</template>

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

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

.app-overlays__header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  min-height: var(--scale-size-48);
  padding-inline: var(--scale-size-16);
}

.app-overlays__content {
  display: flex;
  gap: var(--scale-size-8);
  padding: var(--scale-size-24);
}
</style>

Controlled theme

Bind v-model:theme to own the preference yourself, for example together with Theme Select. Without the prop, the shell manages and persists the preference on its own.

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

const theme = ref<Theme>("system");
</script>

<template>
  <mt-app v-model:theme="theme">
    <template #header>
      <mt-theme-select v-model="theme" label="Color theme" />
    </template>

    <template #content>
      <router-view />
    </template>
  </mt-app>
</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"
    :apply-theme="false"
    :lock-document="false"
  >
    <template #header>
      <div class="app-fullscreen__region">
        <mt-text as="span" size="xs" weight="semibold">Header</mt-text>
      </div>
    </template>

    <template #sidebar-start>
      <div class="app-fullscreen__region app-fullscreen__sidebar">
        <mt-text as="span" size="xs" weight="semibold">Navigation</mt-text>
      </div>
    </template>

    <template #content>
      <div class="app-fullscreen__region">
        <fullscreen-view />
      </div>
    </template>

    <template #sidebar-end>
      <div class="app-fullscreen__region app-fullscreen__sidebar">
        <mt-text as="span" size="xs" weight="semibold">Assistant</mt-text>
      </div>
    </template>
  </mt-app>
</template>

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

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

.app-fullscreen__region {
  padding: var(--scale-size-16);
}

.app-fullscreen__sidebar {
  width: var(--scale-size-160);
}
</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"
    :apply-theme="false"
    :lock-document="false"
  >
    <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 the same elements become modal drawers, so scroll positions and form state inside them survive every layout change. Each drawer has a close button, a backdrop, Escape handling and its own translated accessible name.
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`
`theme` The theme preference. Pass it (or bind `v-model:theme`) to control the theme yourself; omit it to let the shell manage and persist it.	`any`	`undefined`
`theme-storage-key` The `localStorage` key of the persisted theme preference while the theme is not controlled. `null` disables persistence.	`string \| null`	`"mt-theme"`
`apply-theme` Whether the resolved theme is written to the `data-theme` attribute of `<html>`. Disable it for embedded demos that must not touch the page.	`false \| true`	`true`
`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`
`lock-document` Whether the shell owns the document: while mounted, the document never scrolls and the page behind the shell uses the shell background. Disable it when the shell is embedded into a page that scrolls itself.	`false \| true`	`true`
`close-on-navigate` Whether a navigation closes an open drawer. Works automatically with vue-router; with another router, call `closeDrawer()` from `useMtApp()`.	`false \| true`	`true`

Events

Event	Payload
`update:theme`	`[theme: Theme]`
`drawer-change`	`[side: MtAppSide \| null]`

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.
Set --mt-app-height when the shell is embedded and does not own the viewport.

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, which embedded demos use.
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. Set lockDocument to false when the shell is embedded in a page that scrolls. 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 (unless closeOnNavigate is false), 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. With a theme prop the theme is controlled and changes are reported through update:theme; without it the shell persists the preference under themeStorageKey. The resolved theme is written to <html data-theme> unless applyTheme is false.
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	shell
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 shell 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.

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.