App Bar

The m3e-app-bar component is a prominent user interface component that provides consistent access to key actions, navigation, and contextual information at the top of an application screen.

import "@m3e/web/app-bar";
Usage

This section outlines usage examples and configuration guidance for the components in this module.

Anatomy

The m3e-app-bar component provides a structured layout for top-level navigation and contextual information. It exposes the following named slots:

Top 10 hiking trails Discover popular trails
<m3e-app-bar>
  <m3e-icon-button slot="leading" aria-label="Back">
    <m3e-icon name="arrow_back"></m3e-icon>
  </m3e-icon-button>
  <span slot="title">Top 10 hiking trails</span>
  <span slot="subtitle">Discover popular trails</span>
  <m3e-icon-button slot="trailing" aria-label="Bookmark" variant="tonal">
    <m3e-icon name="bookmark" filled></m3e-icon>
  </m3e-icon-button>
</m3e-app-bar>
Sizes

There are three size variants: small (default), medium, and large. Use the size attribute to control an app bar's size.

Top 10 hiking trails Discover popular trails
Top 10 hiking trails Discover popular trails
<m3e-app-bar size="medium">
  <!-- Content omitted for brevity -->
</m3e-app-bar>
<m3e-app-bar size="large">
  <!-- Content omitted for brevity -->
</m3e-app-bar>
Centered

A centered app bar ensures that its primary content — the title and optional subtitle — remains visually centered within the available horizontal space, regardless of the number or size of elements in the leading or trailing slots.

This is achieved through layout symmetry, not equal spacing. The title area is anchored to the center of the container, while icons on either side are allowed to vary in number or width without shifting the title's position.

Top 10 hiking trails Discover popular trails
<m3e-app-bar centered>
  <!-- Content omitted for brevity -->
</m3e-app-bar>
Scroll behavior

An m3e-app-bar can be attached to a scrollable container using the for attribute, which references the container's id. This establishes a scroll contract between the app bar and its content region: the app bar listens to the container's scroll position and reacts as the user scrolls. For the app bar to stay in view, give the container a bounded height with overflow-y: auto and make the app bar position: sticky with top: 0. The scroll-behavior attribute selects how the app bar reacts: elevate (the default), transparent, hide, or compress.

Elevate

With the default elevate behavior, as the user scrolls:

This behavior enhances contextual clarity, signaling that content is in motion while preserving the app bar's role as a stable anchor. The on-scroll appearance is controlled by --m3e-app-bar-container-color-on-scroll and --m3e-app-bar-container-elevation-on-scroll.

Top 10 hiking trails Discover popular trails
Scroll down to see the elevation behavior
<div id="scrollContainer">
  <m3e-app-bar for="scrollContainer">
    <!-- Content omitted for brevity -->
  </m3e-app-bar>
  <div class="scroll-item">Scroll down to see the elevation behavior</div>
</div>
<style>
  #scrollContainer {
    overflow-y: auto;
    height: 300px;
  }
  m3e-app-bar[for="scrollContainer"] {
    position: sticky;
    top: 0;
  }
  .scroll-item {
    height: 400px;
    display: flex;
    align-items: center;
    justify-content: center;
  }
</style>
Transparent

When scroll-behavior is set to transparent, the app bar looks normal at the top of the container. As the user scrolls, the container color and the title and subtitle fade out, while leading and trailing content stays fully opaque. Buttons and icon buttons inside the app bar gain a container color, matching how a toolbar styles its buttons, that fades in with the scroll position.

Top 10 hiking trails Discover popular trails
Scroll down to see the transparent behavior
<div id="scrollContainer">
  <m3e-app-bar for="scrollContainer" scroll-behavior="transparent">
    <!-- Content omitted for brevity -->
  </m3e-app-bar>
  <div class="scroll-item">Scroll down to see the transparent behavior</div>
</div>
Hide

When scroll-behavior is set to hide, the app bar slides out of view by the amount scrolled down, up to its own height. It only slides back in as the scroll position nears the top, where it is fully visible.

Top 10 hiking trails Discover popular trails
Scroll down to hide, up to reveal
Keep scrolling
<div id="scrollContainer">
  <m3e-app-bar for="scrollContainer" scroll-behavior="hide">
    <!-- Content omitted for brevity -->
  </m3e-app-bar>
  <div class="scroll-item">Scroll down to hide, up to reveal</div>
</div>
Compress

When scroll-behavior is set to compress, medium and large app bars collapse to a small app bar in step with the scroll position, instead of elevating. The title and subtitle slide and fade out as the bar collapses, and back in as it expands. The container color and elevation blend toward their on-scroll values as the bar collapses. The on-scroll elevation is flat by default, so only the color changes unless you set --m3e-app-bar-container-elevation-on-scroll. Once scrolling goes idle mid-collapse, the bar finishes the collapse in the direction of the last scroll, moving the scroll position with it. Small app bars have nothing to collapse, so compress has no effect on them.

Top 10 hiking trails Discover popular trails
Scroll down to compress the medium app bar
Top 10 hiking trails Discover popular trails
Scroll down to compress the large app bar
<div id="scrollContainer">
  <m3e-app-bar for="scrollContainer" size="large" scroll-behavior="compress">
    <!-- Content omitted for brevity -->
  </m3e-app-bar>
  <div class="scroll-item">Scroll down to compress the app bar</div>
</div>
Accessibility

By default, app bars are given the ARIA role="banner" to identify them as the site-wide landmark region for branding, navigation, or contextual identity. This role signals to assistive technologies that the app bar serves as the top-level heading for the page or application.

An app bar may only expose the banner landmark when it is at the top of its landmark context. If it is nested inside an element whose role is not document, application, or main, the banner role is automatically removed and the app bar is treated as a neutral, non-semantic element. When no ancestor has a role at all, the app bar is considered top-level and its banner role is preserved. Native module support

The @m3e/web package uses JavaScript Modules. To use it directly in a browser without a bundler, use a module script similar to the following.

<script type="module" src="/node_modules/@m3e/web/dist/app-bar.js"></script>

In addition, you must use an import map to include additional dependencies.

<script type="importmap">
  {
    "imports": {
      "tslib": "https://cdn.jsdelivr.net/npm/tslib@2.8.1/+esm",
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "lit/": "https://cdn.jsdelivr.net/npm/lit@3.3.0/",
      "lit-html": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/+esm",
      "lit-html/directive.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directive.js",
      "lit-html/directives/if-defined.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directives/if-defined.js",
      "lit-html/directives/class-map.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directives/class-map.js",
      "@lit/reactive-element": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.0.4/+esm",
      "@lit/reactive-element/": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.0.4/",
      "@m3e/web/core": "/node_modules/@m3e/web/dist/core.js"
    }
  }
</script>

For production builds, use the minified files to ensure optimal load performance.

API

The @m3e/web package includes a Custom Elements Manifest (custom-elements.json), which documents the properties, attributes, slots, events and CSS custom properties of each component.

You can explore the API below, or integrate the manifest into your own tooling.

m3e-app-bar
On this page App Bar