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.

npm i @m3e/app-bar

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

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

• leading-icon — 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-icon — 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-icon" 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-icon" 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-icon or trailing-icon 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. As the user scrolls:

• The app bar's background becomes elevated — typically via a shadow or surface tone — to signal separation from the content.
• When the scroll position returns to the top, the elevation is removed, restoring a flat visual hierarchy.

This behavior enhances contextual clarity, signaling that content is in motion while preserving the app bar's role as a stable anchor.

<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 effect</div>
</div>
<m3e-app-bar centered>
<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>

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.

This 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/app-bar/dist/index.js"></script>

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

<script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "@m3e/core": "/node_modules/@m3e/core/dist/index.js"
    }
  }
</script>

For production, use index.min.js for faster load times.

This 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.