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";
This section outlines usage examples and configuration guidance for the components in this module.
The m3e-app-bar component provides a structured layout for top-level navigation and contextual
information. It exposes the following named slots:
leading — typically a navigation affordance such as a back arrow or menu button. Positioned at
the start of the bar.
title — The primary label for the current view or context. Usually a short, expressive heading.
subtitle — An optional secondary label that provides additional context or hierarchy beneath
the title.
trailing — One or more action buttons aligned to the end of the bar. Common examples include
search, bookmark, or overflow menus.
<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>
There are three size variants: small (default), medium, and large. Use
the size attribute to control an app bar's size.
<m3e-app-bar size="medium"> <!-- Content omitted for brevity --> </m3e-app-bar> <m3e-app-bar size="large"> <!-- Content omitted for brevity --> </m3e-app-bar>
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.
<m3e-app-bar centered> <!-- Content omitted for brevity --> </m3e-app-bar>
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.
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.
<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>
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.
<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>
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.
<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>
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.
<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>
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.
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.
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.
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.