Top App Bar

Top app bars display application title, navigation, and actions. Supports small, center-aligned, medium, and large variants with optional scroll collapse. Not intended to carry dense secondary tools better suited to dedicated toolbars.

Basic Usage

Simple top app bar with title, navigation icon, and action buttons. This anchors identity and global actions at the top of the viewport. 

<ds-app-bar-top title="Mail" nav-icon="menu">
  <button slot="actions" aria-label="Search" class="material-symbols-outlined">search</button>
  <button slot="actions" aria-label="More" class="material-symbols-outlined">more_vert</button>
</ds-app-bar-top>

Variants

Material Design 3 top app bar variants for different layouts and content needs.

Small

Default compact app bar (64px height) with title, navigation, and action buttons. 

<ds-app-bar-top title="Inbox" nav-icon="menu">
  <button slot="actions" aria-label="Search" class="material-symbols-outlined">search</button>
  <button slot="actions" aria-label="More" class="material-symbols-outlined">more_vert</button>
</ds-app-bar-top>

Center-Aligned

Centers the title while keeping navigation and actions at the edges. 

<ds-app-bar-top variant="center" title="Gallery" nav-icon="arrow_back">
  <button slot="actions" aria-label="Favorite" class="material-symbols-outlined">favorite</button>
</ds-app-bar-top>

Medium

Shows optional subtitle for additional context (112px height).

<ds-app-bar-top variant="medium" title="Project" subtitle="Q4 roadmap" nav-icon="menu">
  <button slot="actions" aria-label="Share" class="material-symbols-outlined">share</button>
  <button slot="actions" aria-label="Filter" class="material-symbols-outlined">filter_list</button>
</ds-app-bar-top>

Large

Largest variant with prominent title and subtitle space (152px height). 

<ds-app-bar-top variant="large" title="Analytics" subtitle="Weekly performance" nav-icon="arrow_back">
  <button slot="actions" aria-label="Refresh" class="material-symbols-outlined">refresh</button>
  <button slot="actions" aria-label="Export" class="material-symbols-outlined">file_download</button>
</ds-app-bar-top>

States

Interactive states and scroll behavior for the app bar.

Default State

Standard app bar with full title and subtitle (medium variant).

<ds-app-bar-top variant="medium" title="Settings" subtitle="Preferences" nav-icon="arrow_back">
  <button slot="actions" aria-label="Save" class="material-symbols-outlined">save</button>
</ds-app-bar-top>

Scrolled State

Apply the scrolled attribute to collapse height and hide subtitle (responsive to scroll events).

Set scrolled Unset scrolled 
<ds-app-bar-top scrolled variant="large" title="Docs" subtitle="Scroll state" nav-icon="menu">
  <button slot="actions" aria-label="Search" class="material-symbols-outlined">search</button>
</ds-app-bar-top>

Interactive Example

Trigger navigation and observe emitted events.

Trigger navigation Trigger save
Action events: none
<ds-app-bar-top id="interactive-app-bar" title="Interactive" nav-icon="menu">
  <button slot="actions" aria-label="Save" class="material-symbols-outlined">save</button>
</ds-app-bar-top>
<button id="trigger-nav">Trigger navigation</button>
<div id="navigation-log">Navigation events: none</div>

API

DSAppBarTop

Container for top app bar variants.

Attributes

Attribute Type Default Description
variant "small" | "center" | "medium" | "large" "small" Selects the visual style
title string - Title text (fallback if no title slot)
subtitle string - Secondary text (medium/large only; hidden when scrolled)
nav-icon string - Material Symbol name for fallback navigation button
scrolled boolean false Collapses to small height, hides subtitle, adds elevation

Slots

Slot Description
navigation Leading navigation control (drawer, back)
actions Trailing action buttons
title Custom title content
subtitle Custom subtitle (medium/large)
(default) Title fallback text

Events

Event Detail Description
ds-app-bar:navigation {} Fired when fallback nav button is clicked

CSS Parts

Part Description
container App bar container
navigation Leading nav region
title Title wrapper
subtitle Subtitle text
actions Trailing actions region
nav-button Fallback navigation button

CSS Custom Properties

Property Default Description
--ds-app-bar-bg --md-sys-color-surface Background color
--ds-app-bar-color --md-sys-color-on-surface Foreground color
--ds-app-bar-shadow none (or shadow when scrolled) Box shadow/elevation
--ds-app-bar-hover-color --md-sys-color-on-surface State layer color
--ds-app-bar-hover-opacity 0.08 Hover state opacity
--ds-app-bar-pressed-opacity 0.12 Pressed state opacity

Accessibility

  • Landmark: App bar uses role="banner"
  • Navigation: Provide clear aria-label for nav/action buttons
  • Keyboard: Tab to buttons, activate with Enter/Space
  • Focus: Visible focus rings on controls

Usage Guidelines

  • When to use: Use top app bars to anchor product identity, navigation entry points, and global actions.
  • When not to use: Avoid overcrowding the bar with contextual tools better placed in page content or secondary toolbars.
  • Composition: Choose variant size based on content density and scroll behavior requirements for each page type.
  • Common mistakes: Too many action icons reduce discoverability. Prioritize the most frequent actions and move overflow to menus.