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:

  1. When the scroll-target attribute is specified. In this case, padding-top is added to the element specified by scroll-target.
  2. 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.

Shape

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

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

Example: Add Shadow on Scroll

Example: Shrink on Scroll

Example: Shrink and Add Shadow on Scroll

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.

mdui-top-app-bar API

Properties

AttributePropertyReflectTypeDefault
variantvariant'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.
hidehidebooleanfalse

Hide the top app bar.

shrinkshrinkbooleanfalse

Shrinks the app bar to small style. Only applicable for medium or large variants.

scroll-behaviorscrollBehavior'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-targetscrollTargetstring | HTMLElement | JQ<HTMLElement>-

The element that listens for scroll events. Accepts a CSS selector, DOM element, or JQ object. Defaults to window.

scroll-thresholdscrollThresholdnumber-

The scroll distance (in pixels) that triggers the scroll behavior.

orderordernumber-

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.

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.

MDUIDocsEnglish简体中文LightDarkSystem
Preset Colors
Custom Color
Extract Color from Wallpaper
Select a Wallpaper
Getting Started
Introduction Installation Usage TypeScript Support IDE Support Localization Frequently Asked Questions
Styles
Dark Theme Dynamic Theme Typography Design Tokens
Frameworks
React Vue Angular
Components
Button ButtonIcon Fab SegmentedButton Chip Card Checkbox Radio Switch Slider RangeSlider List Collapse Tabs Dropdown Menu Select TextField LinearProgress CircularProgress Dialog Divider Avatar Badge Icon Tooltip Snackbar NavigationBar NavigationDrawer NavigationRail BottomAppBar TopAppBar Layout
Functions
JavaScript Library dialog alert confirm prompt snackbar getTheme setTheme getColorFromImage setColorScheme removeColorScheme loadLocale setLocale getLocale throttle observeResize breakpoint
Libraries
@mdui/icons