@m3e/app-bar

@m3e/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. Designed according to Material 3 principles, it organizes content with clear hierarchy, supports dynamic color, elevation, alignment, and adapts to scrolling behavior.

This package is part of M3E monorepo, a unified suite of Material 3 web components. Explore the docs to see them in action.

📦 Installation

npm install @m3e/app-bar

💻 Editor Integration

This package includes a Custom Elements Manifest to support enhanced editor tooling and developer experience.

Visual Studio Code

To enable autocomplete and hover documentation for @m3e/app-bar, install the Custom Elements Manifest Language Server extension. It will automatically detect the manifest bundled with this package and surface tag names, attributes, slots, and events in supported files.

Alternately, you can explicitly reference the html-custom-data.json and css-custom-data.json in your workspace settings:

{
  "html.customData": ["./node_modules/@m3e/app-bar/dist/html-custom-data.json"],
  "css.customData": ["./node_modules/@m3e/app-bar/dist/css-custom-data.json"]
}

🚀 Native Module Support

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

🗂️ Elements

• m3e-app-bar — A bar, placed a the top of a screen, used to help users navigate through an application.

🧪 Examples

The following example illustrates a medium size m3e-app-bar consisting of a leading button, title, subtitle, and trailing button.

This example uses the @m3e/icon package to present Material Design symbols, but any icon package can be substituted depending on your design system or preferences

<m3e-app-bar size="medium">
  <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>

The next example illustrates how to attach an app bar to a parent scroll container to produce elevation on scroll. In this example, the for attribute is used to attach a sticky-positioned m3e-app-bar to a parenting container styled to overflow vertically. When scrolled, the app bar will automatically transition to an elevated state.

<div style="overflow-y: auto; height: 300px" id="scrollContainer">
  <m3e-app-bar for="scrollContainer" style="position: sticky; top: 0">
    <span slot="title">Title</span>
  </m3e-app-bar>
  <div style="height: 400px; display: flex; align-items: center; justify-content: center">I am scrolling content</div>
</div>

📖 API Reference

This section details the attributes, slots and CSS custom properties available for the m3e-app-bar component.

⚙️ Attributes

Attribute	Type	Default	Description
centered	boolean	false	Whether the title and subtitle are centered.
size	"small" | "medium" | "large"	"small"	The size of the bar.
for	string		The identifier of the interactive control to which this element is attached.

🧩 Slots

Slot	Description
leading-icon	Renders a leading icon.
title	Renders the title.
subtitle	Renders the subtitle.
trailing-icon	Renders a trailing icon.

🎛️ CSS Custom Properties

The m3e-app-bar component supports theming via scoped CSS custom properties for layout, color, elevation, and interaction states.

Container & Color Properties

Property	Description
--m3e-app-bar-container-color	Background color of the app bar container.
--m3e-app-bar-container-color-on-scroll	Background color when scrolled.
--m3e-app-bar-container-elevation	Elevation (shadow) of the app bar container.
--m3e-app-bar-container-elevation-on-scroll	Elevation (shadow) when scrolled.
--m3e-app-bar-title-text-color	Color of the app bar title text.
--m3e-app-bar-subtitle-text-color	Color of the app bar subtitle text.
--m3e-app-bar-padding-left	Left padding for the app bar container.
--m3e-app-bar-padding-right	Right padding for the app bar container.

Small Size Properties

Property	Description
--m3e-app-bar-small-container-height	Height of the small app bar container.
--m3e-app-bar-small-title-text-font-size	Font size for the small app bar title text.
--m3e-app-bar-small-title-text-font-weight	Font weight for the small app bar title text.
--m3e-app-bar-small-title-text-line-height	Line height for the small app bar title text.
--m3e-app-bar-small-subtitle-text-tracking	Letter spacing for the small app bar title text.
--m3e-app-bar-small-subtitle-text-font-size	Font size for the small app bar subtitle text.
--m3e-app-bar-small-subtitle-text-font-weight	Font weight for the small app bar subtitle text.
--m3e-app-bar-small-subtitle-text-line-height	Line height for the small app bar subtitle text.
--m3e-app-bar-small-heading-padding-left	Left padding for the small app bar heading.
--m3e-app-bar-small-heading-padding-right	Right padding for the small app bar heading.

Medium Size Properties

Property	Description
--m3e-app-bar-medium-container-height	Height of the medium app bar container.
--m3e-app-bar-medium-container-height-with-subtitle	Height of the medium app bar with subtitle.
--m3e-app-bar-medium-title-text-font-size	Font size for the medium app bar title text.
--m3e-app-bar-medium-title-text-font-weight	Font weight for the medium app bar title text.
--m3e-app-bar-medium-title-text-line-height	Line height for the medium app bar title text.
--m3e-app-bar-medium-subtitle-text-tracking	Letter spacing for the medium app bar title text.
--m3e-app-bar-medium-subtitle-text-font-size	Font size for the medium app bar subtitle text.
--m3e-app-bar-medium-subtitle-text-font-weight	Font weight for the medium app bar subtitle text.
--m3e-app-bar-medium-subtitle-text-line-height	Line height for the medium app bar subtitle text.
--m3e-app-bar-medium-heading-padding-left	Left padding for the medium app bar heading.
--m3e-app-bar-medium-heading-padding-right	Right padding for the medium app bar heading.
--m3e-app-bar-medium-padding-top	Top padding for the medium app bar.
--m3e-app-bar-medium-padding-bottom	Bottom padding for the medium app bar.
--m3e-app-bar-medium-title-max-lines	Max lines for the medium app bar title.
--m3e-app-bar-medium-subtitle-max-lines	Max lines for the medium app bar subtitle.

Large Size Properties

Property	Description
--m3e-app-bar-large-container-height	Height of the large app bar container.
--m3e-app-bar-large-container-height-with-subtitle	Height of the large app bar with subtitle.
--m3e-app-bar-large-title-text-font-size	Font size for the large app bar title text.
--m3e-app-bar-large-title-text-font-weight	Font weight for the large app bar title text.
--m3e-app-bar-large-title-text-line-height	Line height for the large app bar title text.
--m3e-app-bar-large-subtitle-text-tracking	Letter spacing for the large app bar title text.
--m3e-app-bar-large-subtitle-text-font-size	Font size for the large app bar subtitle text.
--m3e-app-bar-large-subtitle-text-font-weight	Font weight for the large app bar subtitle text.
--m3e-app-bar-large-subtitle-text-line-height	Line height for the large app bar subtitle text.
--m3e-app-bar-large-heading-padding-left	Left padding for the large app bar heading.
--m3e-app-bar-large-heading-padding-right	Right padding for the large app bar heading.
--m3e-app-bar-large-padding-top	Top padding for the large app bar.
--m3e-app-bar-large-padding-bottom	Bottom padding for the large app bar.
--m3e-app-bar-large-title-max-lines	Max lines for the large app bar title.
--m3e-app-bar-large-subtitle-max-lines	Max lines for the large app bar subtitle.

🤝 Contributing

See the root monorepo CONTRIBUTING.md for guidelines on contributing to this package.

📄 License

This package is licensed under the MIT License.