Navigation

Top App Bar

MD3 top app bar — small, medium, large and center-aligned.

import { TopAppBar } from 'omaris'

Examples

Sizes

Small, centred, medium and large — the four MD3 shapes. small for a dense dashboard page, large where the headline is the point.

September revenue

1<script lang="ts">2	import { IconButton, TopAppBar } from 'omaris';3</script>45{#snippet back()}6	<IconButton aria-label="Back">7		<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8">8			<path d="M15 5l-7 7 7 7" stroke-linecap="round" stroke-linejoin="round" />9		</svg>10	</IconButton>11{/snippet}1213<div class="flex w-full flex-col gap-4">14	<div class="overflow-hidden rounded-shape-lg border border-border">15		<TopAppBar size="small" title="September revenue" variant="surface">16			{#snippet leading()}{@render back()}{/snippet}17		</TopAppBar>18	</div>19	<div class="overflow-hidden rounded-shape-lg border border-border">20		<TopAppBar size="center" title="September revenue" variant="surface">21			{#snippet leading()}{@render back()}{/snippet}22		</TopAppBar>23	</div>24	<div class="overflow-hidden rounded-shape-lg border border-border">25		<TopAppBar size="medium" title="September revenue" variant="surface">26			{#snippet leading()}{@render back()}{/snippet}27		</TopAppBar>28	</div>29	<div class="overflow-hidden rounded-shape-lg border border-border">30		<TopAppBar size="large" title="September revenue" variant="surface">31			{#snippet leading()}{@render back()}{/snippet}32		</TopAppBar>33	</div>34</div>

Actions

leading and actions are the two ends; the title takes what is left. A back arrow on a detail screen, a menu button when the drawer is modal.

Inbox

1<script lang="ts">2	import { Badge, IconButton, TopAppBar } from 'omaris';3</script>45<div class="w-full overflow-hidden rounded-shape-lg border border-border">6	<TopAppBar title="Inbox" variant="surface">7		{#snippet leading()}8			<IconButton aria-label="Open navigation">9				<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8">10					<path d="M4 7h16M4 12h16M4 17h16" stroke-linecap="round" />11				</svg>12			</IconButton>13		{/snippet}14		{#snippet actions()}15			<span class="relative inline-flex">16				<IconButton aria-label="Notifications">17					<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8">18						<path d="M18 16V11a6 6 0 1 0-12 0v5l-2 3h16z" stroke-linejoin="round" />19					</svg>20				</IconButton>21				<Badge anchor="top-end" value={12} tone="destructive" label="12 unread" />22			</span>23			<IconButton aria-label="More">24				<svg viewBox="0 0 24 24" fill="currentColor">25					<circle cx="12" cy="5" r="1.6" /><circle cx="12" cy="12" r="1.6" /><circle26						cx="12"27						cy="19"28						r="1.6"29					/>30				</svg>31			</IconButton>32		{/snippet}33	</TopAppBar>34</div>

Scroll behaviour

sticky holds it at the top of the scrolling column, and it takes elevation the moment there is content under it. flexible shrinks a large headline into a small bar as you scroll — try it.

September revenue

1<script lang="ts">2	import { AppShell, AppShellMain, AppShellContent, TopAppBar } from 'omaris';3</script>45<div class="h-80 w-full overflow-hidden rounded-shape-lg border border-border">6	<AppShell class="h-full">7		<AppShellMain>8			<TopAppBar size="large" title="September revenue" flexible sticky variant="surface" />9			<AppShellContent width="md">10				<div class="flex flex-col gap-3">11					{#each { length: 14 }, i (i)}12						<div class="h-12 rounded-shape-md bg-surface-container"></div>13					{/each}14				</div>15			</AppShellContent>16		</AppShellMain>17	</AppShell>18</div>

When to use it

Use it for

The top of every screen in an App Shell: the screen's title, a leading back arrow or menu button, and up to three actions.
A long read, like a report or a document. size="large" with flexible collapses the headline into a small bar as the page scrolls.
The dashboard's top bar: a Search Bar in the search slot, navigation on the left, the account on the right.
A map or a canvas. floating detaches it into a rounded, blurred capsule over the content.
A tab row under the bar, passed as children. It moves with the bar.

Not for

The app's navigation → Navigation Drawer or Navigation Bar. The bar carries one screen's title and actions.
A bar plus a filter row that stick together → wrap both in an AppShellHeader from App Shell.
A headline with no actions, halfway down a page → Text with variant="headline-md".
A selection bar like "3 selected, delete" → a sticky AppShellFooter from App Shell, at the bottom.

Do

Set sticky. It does not stick on its own. Inside a shell it knows which column scrolls; scrollContainer is only for other layouts.
Use one leading control: back on a detail screen, the menu button when the drawer is modal, nothing on a top-level screen.
Keep to three icon actions. The rest go in a Menu behind the last one.
Pick size by the screen: small for a dense dashboard page, medium or large where the headline is the point, center on a top-level screen with one action.

Don't

Stack two bars. The tab row is children; the search is search.
Set hideOnScroll on a screen whose actions people use while they work. It is for reading.
Use variant="surface" on a flat page. flat is flat at rest and lifts once content scrolls under it.
Expect title and search together on a small bar. search replaces the middle; only medium and large keep the headline on the row below.

Pairs with App Shell Navigation Drawer Search Bar Tabs Icon Button Menu

Quick reference

size

small (default)
center
medium
large

variant

flat (default)
surface
transparent

API

TopAppBar

MD3 top app bar — small, medium, large and center-aligned.

The MD3 behaviour that matters is the scroll response, and it's all wired here so a consumer doesn't rebuild it per screen:

- The bar is flat on a page at rest and lifts onto a raised surface once the content scrolls under it. - flexible gives a medium or large bar the collapse MD3 calls for: the big headline shrinks and fades on the way up while the same text fades in beside the actions, so the bar ends as a small one. - hideOnScroll gets the bar out of the way entirely on the way down and brings it back the moment you scroll up. - floating detaches it from the edges — the rounded, blurred bar that hovers over a map or a canvas.

medium and large drop the headline onto its own line below the actions, which is where MD3 puts it. Put a SearchBar in the search slot and the bar becomes the search bar of a dashboard.

import { TopAppBar } from 'omaris'

Parts

Every element this renders is reachable from outside. Pass Tailwind for one part as classes={{ part: '…' }}; class covers the root and is merged last, so it always wins.

root: No description in the source yet.
bar: The action row: leading control, title, trailing controls.
leading: No description in the source yet.
title: No description in the source yet.
actions: No description in the source yet.
headlineRow: Clips the second-line headline while it collapses.
headline: The second-line headline on a medium or large bar.
search: Full-width middle slot — a search field, usually.

Props

size

Defaults to 'small'

TopAppBarSize

small
center
medium
large

variant

Defaults to 'flat'

TopAppBarVariant

flat: Sits on the page background until it's scrolled under.
surface: Always on a raised surface.
transparent: No background at all — over a hero image, say.

title

string

Headline text.

sticky

Defaults to false

boolean

Stick to the top of the scroll container.

floating

Defaults to false

boolean

Rounded, blurred and inset from the edges.

elevateOnScroll

Defaults to true

boolean

Lift onto a raised surface once the page is scrolled. Give it a scroll container element to watch something other than the window.

flexible

Defaults to false

boolean

Collapse a medium or large bar into a small one as the page scrolls — MD3's flexible bar.

collapseDistance

number

Scroll distance the collapse runs over, in px. Defaults to the headline's own height, which is the distance it has to travel.

hideOnScroll

Defaults to false

boolean

Slide the bar away while scrolling down; bring it back on the way up.

scrollContainer

HTMLElement | null

What to watch for scrolling. Inside an AppShell this is already known — the shell hands over its scrolling column — so it's only needed for a layout that scrolls something else. null is the window, explicitly.

threshold

Defaults to 4

number

Scroll distance, in px, before the bar lifts.

progress bindable

Defaults to 0

number

How far the collapse has run, 0…1. Bindable, read-only in practice.

class

string

classes

TopAppBarClasses

Per-part Tailwind overrides. class still covers the root.

leading

Snippet

Leading control — a back arrow or menu button.

headline

Snippet

Rich headline, in place of title.

actions

Snippet

Trailing controls.

search

Snippet

Takes over the middle of the action row, full width — a SearchBar, usually. It replaces what sits there rather than joining it, so on a small or centred bar title is not drawn at all while this is set. A medium or large bar still draws its headline on the row below, so those keep both.

children

Snippet

Anything below the bar — a tab row.