# Top App Bar Component

The Top App Bar provides context and actions for the current screen, supporting branding, navigation, search, and other actions.

## Usage {#usage}

Import the component:

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

Import the TypeScript type:

```ts
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. Don't include it in production.)

```html
<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 the component is used inside the [`<mdui-layout></mdui-layout>`](/en/docs/2/components/layout) component. In this case, `padding-top` is not added.

## Examples {#examples}

### In Container {#example-scroll-target}

By default, the top app bar is fixed to the top of the viewport.

To place the top app bar inside a container, set the `scroll-target` attribute on the `<mdui-top-app-bar>` component to the CSS selector or DOM element of the scrollable container. In this case, the top app bar is positioned relative to its parent element. Be sure to add the styles `position: relative; overflow: hidden` to the parent element yourself.

```html
<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>
```

### Shape {#example-variant}

The `variant` attribute on the `<mdui-top-app-bar>` component controls the top app bar's shape.

```html
<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>
```

### Scroll Behavior {#example-scroll-behavior}

The `scroll-behavior` attribute on the `<mdui-top-app-bar>` component defines how the top app bar behaves when the page is scrolled. You can use multiple scroll behaviors at once by separating them with spaces.

Scroll behaviors include:

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

The `scroll-threshold` attribute sets how many pixels must be scrolled before the top app bar starts reacting. Do not set `scroll-threshold` when using `elevate`, so it responds immediately.

**Example: Hide on Scroll**

```html
<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>
```

**Example: Add Shadow on Scroll**

```html
<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>
```

**Example: Shrink on Scroll**

```html
<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>
```

**Example: Shrink and Add Shadow on Scroll**

```html
<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>
```

### Expanded State Text {#label-large}

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.

```html
<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>
```

## mdui-top-app-bar-title API

### Slots

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(default)</td>
    <td><p>The title text of the top app bar.</p>
</td>
  </tr>
  <tr>
    <td>label-large</td>
    <td><p>The title text when the top app bar is in the expanded state.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Parts

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>label</td>
    <td><p>The title text.</p>
</td>
  </tr>
  <tr>
    <td>label-large</td>
    <td><p>The title text when the top app bar is in the expanded state.</p>
</td>
  </tr>
</tbody>
</table>

## mdui-top-app-bar API

### Properties

<table>
<thead>
  <tr>
    <th>Attribute</th>
    <th>Property</th>
    <th>Reflect</th>
    <th>Type</th>
    <th>Default</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>variant</td>
    <td>variant</td>
    <td>true</td>
    <td>&#39;center-aligned&#39; | &#39;small&#39; | &#39;medium&#39; | &#39;large&#39;</td>
    <td>'small'</td>
    <td><p>Defines the top app bar variant. Default is <code>small</code>. Possible values:</p>
<ul>
<li><code>center-aligned</code>: A small app bar with a centered title.</li>
<li><code>small</code>: Small app bar.</li>
<li><code>medium</code>: Medium-sized app bar.</li>
<li><code>large</code>: Large-sized app bar.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>hide</td>
    <td>hide</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Whether the top app bar is hidden.</p>
</td>
  </tr>
  <tr>
    <td>shrink</td>
    <td>shrink</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Shrinks the app bar to the <code>small</code> variant. Only applies to <code>medium</code> or <code>large</code> variants.</p>
</td>
  </tr>
  <tr>
    <td>scroll-behavior</td>
    <td>scrollBehavior</td>
    <td>true</td>
    <td>&#39;hide&#39; | &#39;shrink&#39; | &#39;elevate&#39;</td>
    <td></td>
    <td><p>Defines the scroll behavior. Multiple space-separated values are accepted. Possible values:</p>
<ul>
<li><code>hide</code>: Hides when scrolling.</li>
<li><code>shrink</code>: Shrinks when scrolling (for medium to large app bars).</li>
<li><code>elevate</code>: Increases elevation when scrolling.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>scroll-target</td>
    <td>scrollTarget</td>
    <td>false</td>
    <td>string | HTMLElement | JQ&lt;HTMLElement&gt;</td>
    <td></td>
    <td><p>The element to watch for scroll events. Accepts a CSS selector, a DOM element, or a <a href="/en/docs/2/functions/jq">JQ object</a>. Defaults to <code>window</code>.</p>
</td>
  </tr>
  <tr>
    <td>scroll-threshold</td>
    <td>scrollThreshold</td>
    <td>true</td>
    <td>number</td>
    <td></td>
    <td><p>The scroll distance (in pixels) required to trigger the scroll behavior.</p>
</td>
  </tr>
  <tr>
    <td>order</td>
    <td>order</td>
    <td>true</td>
    <td>number</td>
    <td></td>
    <td><p>Specifies the layout order within the <a href="/en/docs/2/components/layout"><code>&lt;mdui-layout&gt;</code></a> component. Items are sorted in ascending order. The default value is <code>0</code>.</p>
</td>
  </tr>
</tbody>
</table>

### Events

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>show</td>
    <td><p>Emitted when the top app bar starts to show. Can be prevented with <code>event.preventDefault()</code>.</p>
</td>
  </tr>
  <tr>
    <td>shown</td>
    <td><p>Emitted after the top app bar has shown and animations are complete.</p>
</td>
  </tr>
  <tr>
    <td>hide</td>
    <td><p>Emitted when the top app bar starts to hide. Can be prevented with <code>event.preventDefault()</code>.</p>
</td>
  </tr>
  <tr>
    <td>hidden</td>
    <td><p>Emitted after the top app bar has hidden and animations are complete.</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(default)</td>
    <td><p>Elements contained within the top app bar.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Custom Properties

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>--shape-corner</td>
    <td><p>The corner radius of the component. You can use a specific pixel value, but it is recommended to reference <a href="/en/docs/2/styles/design-tokens#shape-corner">design tokens</a>.</p>
</td>
  </tr>
  <tr>
    <td>--z-index</td>
    <td><p>The CSS <code>z-index</code> value of the component.</p>
</td>
  </tr>
</tbody>
</table>