TopAppBar

The Top App Bar provides information and actions related to the current screen, serving as a tool for branding, navigation, search, and actions.

Usage

Import the component:

import 'mdui/components/top-app-bar.js';
import 'mdui/components/top-app-bar-title.js';

Import the TypeScript type:

import type { TopAppBar } from 'mdui/components/top-app-bar.js';
import type { TopAppBarTitle } from 'mdui/components/top-app-bar-title.js';

Example: (Note: The style="position: relative" in the example is for demonstration purposes. Remove it in actual use.)

Title

<mdui-top-app-bar style="position: relative;">
  <mdui-button-icon icon="menu"></mdui-button-icon>
  <mdui-top-app-bar-title>Title</mdui-top-app-bar-title>
  <div style="flex-grow: 1"></div>
  <mdui-button-icon icon="more_vert"></mdui-button-icon>
</mdui-top-app-bar>

Notes:

By default, the top app bar uses position: fixed and automatically adds padding-top to the body to prevent the page content from being obscured.

However, it uses position: absolute in the following cases:

When the scroll-target attribute is specified. In this case, padding-top is added to the element specified by scroll-target.
When it is within the <mdui-layout></mdui-layout> component. In this case, padding-top is not added.

Examples

In Container

By default, the top app bar is positioned relative to the current window and appears at the top of the page.

To place the top app bar inside a container, specify the scroll-target attribute on the <mdui-top-app-bar> component. Set its value to the CSS selector or DOM element of the container with scrollable content. In this case, the top app bar will be positioned relative to the parent element. Ensure to add the styles position: relative; overflow: hidden to the parent element.

Title

<div style="position: relative;overflow: hidden">
  <mdui-top-app-bar scroll-target=".example-scroll-target">
    <mdui-top-app-bar-title>Title</mdui-top-app-bar-title>
  </mdui-top-app-bar>

  <div class="example-scroll-target" style="height: 160px;overflow: auto;">
    <div style="height: 1000px"></div>
  </div>
</div>

Code

Shape

The variant attribute on the <mdui-top-app-bar> component sets the shape of the top app bar.

Title

center-aligned

small

medium

large

<div style="position: relative;overflow: hidden">
  <mdui-top-app-bar variant="small" scroll-target=".example-variant" class="example-variant-bar">
    <mdui-button-icon icon="menu"></mdui-button-icon>
    <mdui-top-app-bar-title>Title</mdui-top-app-bar-title>
    <div style="flex-grow: 1"></div>
    <mdui-button-icon icon="more_vert"></mdui-button-icon>
  </mdui-top-app-bar>

  <div class="example-variant" style="height: 160px;overflow: auto;">
    <div style="height: 1000px">
      <mdui-segmented-button-group selects="single" value="small">
        <mdui-segmented-button value="center-aligned">center-aligned</mdui-segmented-button>
        <mdui-segmented-button value="small">small</mdui-segmented-button>
        <mdui-segmented-button value="medium">medium</mdui-segmented-button>
        <mdui-segmented-button value="large">large</mdui-segmented-button>
      </mdui-segmented-button-group>
    </div>
  </div>
</div>

<script>
  const topAppBar = document.querySelector(".example-variant-bar");
  const segmentedButtonGroup = document.querySelector(".example-variant");

  segmentedButtonGroup.addEventListener("change", (event) => {
    topAppBar.variant = event.target.value;
  });
</script>

Code

Scroll Behavior

The scroll-behavior attribute on the <mdui-top-app-bar> component defines the top app bar's behavior when the page is scrolled. You can use multiple scroll behaviors simultaneously by separating them with spaces.

Scroll behaviors include:

hide: Hides the top app bar when scrolling down and shows it when scrolling up.
shrink: Effective when variant is medium or large. Expands the top app bar when scrolling down and shrinks it when scrolling up.
elevate: Adds a shadow to the top app bar when scrolling down and removes the shadow when scrolling back to the top.

The scroll-threshold attribute sets the number of pixels to start the scroll behavior of the top app bar. (Do not set the scroll-threshold attribute when using the elevate scroll behavior to respond promptly)

Example: Hide on Scroll

Title

<div style="position: relative;overflow: hidden">
  <mdui-top-app-bar
    scroll-behavior="hide"
    scroll-threshold="30"
    scroll-target=".example-scroll-behavior-hide"
  >
    <mdui-button-icon icon="menu"></mdui-button-icon>
    <mdui-top-app-bar-title>Title</mdui-top-app-bar-title>
    <div style="flex-grow: 1"></div>
    <mdui-button-icon icon="more_vert"></mdui-button-icon>
  </mdui-top-app-bar>

  <div class="example-scroll-behavior-hide" style="height: 160px;overflow: auto;">
    <div style="height: 1000px"></div>
  </div>
</div>

Code

Example: Add Shadow on Scroll

Title

<div style="position: relative;overflow: hidden">
  <mdui-top-app-bar
    scroll-behavior="elevate"
    scroll-target=".example-scroll-behavior-elevate"
  >
    <mdui-button-icon icon="menu"></mdui-button-icon>
    <mdui-top-app-bar-title>Title</mdui-top-app-bar-title>
    <div style="flex-grow: 1"></div>
    <mdui-button-icon icon="more_vert"></mdui-button-icon>
  </mdui-top-app-bar>

  <div class="example-scroll-behavior-elevate" style="height: 160px;overflow: auto;">
    <div style="height: 1000px"></div>
  </div>
</div>

Code

Example: Shrink on Scroll

Title

<div style="position: relative;overflow: hidden">
  <mdui-top-app-bar
    variant="medium"
    scroll-behavior="shrink"
    scroll-threshold="30"
    scroll-target=".example-scroll-behavior-shrink"
  >
    <mdui-button-icon icon="menu"></mdui-button-icon>
    <mdui-top-app-bar-title>Title</mdui-top-app-bar-title>
    <div style="flex-grow: 1"></div>
    <mdui-button-icon icon="more_vert"></mdui-button-icon>
  </mdui-top-app-bar>

  <div class="example-scroll-behavior-shrink" style="height: 160px;overflow: auto;">
    <div style="height: 1000px"></div>
  </div>
</div>

Code

Example: Shrink and Add Shadow on Scroll

Title

<div style="position: relative;overflow: hidden">
  <mdui-top-app-bar
    variant="medium"
    scroll-behavior="shrink elevate"
    scroll-target=".example-scroll-behavior-shrink-elevate"
  >
    <mdui-button-icon icon="menu"></mdui-button-icon>
    <mdui-top-app-bar-title>Title</mdui-top-app-bar-title>
    <div style="flex-grow: 1"></div>
    <mdui-button-icon icon="more_vert"></mdui-button-icon>
  </mdui-top-app-bar>

  <div class="example-scroll-behavior-shrink-elevate" style="height: 160px;overflow: auto;">
    <div style="height: 1000px"></div>
  </div>
</div>

Code

Expanded State Text

For a top app bar with variant set to medium or large, and scroll-behavior set to shrink, you can use the label-large slot within the <mdui-top-app-bar-title> component to specify the text displayed in the expanded state.

This is the collapsed state title This is the expanded state title

<div style="position: relative;overflow: hidden">
  <mdui-top-app-bar
    variant="medium"
    scroll-behavior="shrink elevate"
    scroll-target=".example-label-large-slot"
  >
    <mdui-button-icon icon="menu"></mdui-button-icon>
    <mdui-top-app-bar-title>
      This is the collapsed state title
      <span slot="label-large">This is the expanded state title</span>
    </mdui-top-app-bar-title>
    <div style="flex-grow: 1"></div>
    <mdui-button-icon icon="more_vert"></mdui-button-icon>
  </mdui-top-app-bar>

  <div class="example-label-large-slot" style="height: 160px;overflow: auto;">
    <div style="height: 1000px"></div>
  </div>
</div>

Code

`mdui-top-app-bar-title` API

Slots

Name
(default)
The title text of the top app bar.
`label-large`
The title text when the top app bar is in the expanded state.

CSS Parts

Name
`label`
The title text.
`label-large`
The title text when the top app bar is in the expanded state.

`mdui-top-app-bar` API

Properties

Attribute	Property	Type	Default
`variant`	`variant`	`'center-aligned' \| 'small' \| 'medium' \| 'large'`	`'small'`
Defines the top app bar style. Default is `small`. Possible values: `center-aligned`: Small app bar with a center-aligned title. `small`: Small app bar. `medium`: Medium-sized app bar. `large`: Large-sized app bar.
`hide`	`hide`	`boolean`	`false`
Hide the top app bar.
`shrink`	`shrink`	`boolean`	`false`
Shrinks the app bar to `small` style. Only applicable for `medium` or `large` variants.
`scroll-behavior`	`scrollBehavior`	`'hide' \| 'shrink' \| 'elevate'`	-
Defines the scroll behavior. Accepts multiple space-separated values. Possible values: `hide`: Hides when scrolling. `shrink`: Shrinks when scrolling for medium to large app bars. `elevate`: Increases elevation when scrolling.
`scroll-target`	`scrollTarget`	`string \| HTMLElement \| JQ<HTMLElement>`	-
The element that listens for scroll events. Accepts a CSS selector, DOM element, or JQ object. Defaults to `window`.
`scroll-threshold`	`scrollThreshold`	`number`	-
The scroll distance (in pixels) that triggers the scroll behavior.
`order`	`order`	`number`	-
Specifies the layout order within the `<mdui-layout>` component. Items are sorted in ascending order. The default value is `0`.

Events

Name
`show`
Emitted when the top app bar starts to show. Can be prevented with `event.preventDefault()`.
`shown`
Emitted after the top app bar has shown and animations are complete.
`hide`
Emitted when the top app bar starts to hide. Can be prevented with `event.preventDefault()`.
`hidden`
Emitted after the top app bar has hidden and animations are complete.

Slots

Name
(default)
Elements contained within the top app bar.

CSS Custom Properties

Name
`--shape-corner`
The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
`--z-index`
The CSS `z-index` value of the component.

Tooltip

Up Next

JavaScript Library