TopBar

Import

import { TopBar } from '@envsemble/envui';

Usage

A TopBar holds, in reading order:

start content before the title, such as a navigation or back IconButton or the application's mark;
its title, the application's or the section's name, which is no heading and is cut short first;
actions at the end, such as a search trigger and the account menu.

Put it in a Scaffold's top bar region, which is the banner landmark.

AppTopBar.tsx

import { AvatarButton, IconButton, TopBar } from '@envsemble/envui';
import { IconArrowBack } from '@envsemble/envui/icons/ArrowBack';
import { IconSearch } from '@envsemble/envui/icons/Search';

export default function AppTopBar() {
  return (
    <TopBar
      start={<IconButton icon={<IconArrowBack />} aria-label="Back to projects" variant="ghost" />}
      title="Website refresh"
      actions={
        <>
          <IconButton icon={<IconSearch />} aria-label="Search" variant="ghost" />
          <AvatarButton name="Alex Morgan" />
        </>
      }
    />
  );
}

Background

background is default, the navigation's background, as a plain rectangle with no line below, or page, which puts it on the page's background, opaque when it sticks, while the navigation keeps its own. On a surface, such as a Sheet, both take the surface's color.

Page progress

loading shows a thin bar along the bottom edge while the next page loads, after a short delay so quick loads never flash it. loadingLabel names it.

// True while the next page loads from the server.
<TopBar title="Northwind" loading={loading} loadingLabel="Loading Projects" />

Title bar

titleBar makes the bar the window's own title bar in an installed web app that draws its own, through the Window Controls Overlay: empty space drags the window, it leaves room for the controls the system draws, the title is centred and the controls are small.

Put it in a Scaffold with topBarSpan="full".

<TopBar
  titleBar
  title="Roadmap.md"
  start={<Menubar.Root aria-label="Application menu">…</Menubar.Root>}
  actions={<IconButton icon={<IconShare />} aria-label="Share" />}
/>

Outside a Scaffold

sticky keeps a bar outside a Scaffold at the top of the scrolling area as the document scrolls; in a Scaffold's top bar region it is unneeded, since the body scrolls under it.

render={<header />} makes such a bar the page's banner; it is a div by default.

Composition

The parts are the bar, env-top-bar, its start, env-top-bar-start, its title, env-top-bar-title, its actions, env-top-bar-actions, and the page progress, env-top-bar-loading-bar.

Keep the navigation in the Scaffold's navigation region, and two or three actions in the bar, the account last.

Accessibility

You provide

Names for icon-only buttons, such as Search or Back to projects.
A loadingLabel that names what loads, in the application's language.

envUI provides

A plain element, which the Scaffold's banner region names; render gives it another element.
The page progress as a named progress bar while it shows.
In a title bar, controls that stay clickable where the window drags.

Props

The bar at the top of an application or a screen: start content, such as a navigation button or the application's mark, the title, which truncates first, and the actions at the end, in one row that never wraps, at the top bar height. It can stick to the top as the page scrolls, show page progress along its bottom edge, or be the window's own title bar.

Prop	Type	Description
`start`	`ReactNode`	Content before the title, at the inline start: a navigation IconButton, such as one that opens a navigation drawer, a back IconButton, or the application's mark.
`title`	`ReactNode`	The title, such as the application's or the section's name. It truncates before the start content and the actions shrink. It is no heading: the page's own heading is its PageHeader's.
`actions`	`ReactNode`	The actions at the inline end, such as a search trigger, a theme toggle and an account menu, in the order people read them.
`sticky`Default `false`	`boolean`	Keeps the bar at the top of the scrolling area as it scrolls, for a bar in a page whose document scrolls. In a Scaffold's top bar region it is unneeded: the body scrolls under it.
`titleBar`Default `false`	`boolean`	The bar is the window's title bar, in an installed web app or a desktop shell that draws its own (the Window Controls Overlay): empty space drags the window, it leaves room for the window controls the system draws, the title is centered, and its controls are small, with buttons that set no variant ghost. Put it in a Scaffold with topBarSpan="full".
`background`Default `'default'`	`'default''page'`	The bar's background, named as Surface's and Card's: default, the navigation's background, the default surface color, as a plain rectangle; page, the page's background, so it sits on the page. On a surface, such as a Sheet, both take the surface's color. Set it on its own, such as a TopBar with page over a NavigationDrawer with its background.
`loading`Default `false`	`boolean`	Shows page progress along the bar's bottom edge, such as while the next page loads.
`loadingLabel`Default `'Loading page', or EnvUIProvider's messages.topBar.loading`	`string`	The progress bar's name.
`render`	`ReactElement`	The element to render, such as render={<header />} for a bar outside a Scaffold, which then is the page's banner; a div by default, as Scaffold's top bar region is the banner.
`skeleton`Default `false`	`boolean`	Shows it and its content as a busy skeleton while that loads; turning it on or off renders the content anew.

Also accepts the native props of <div>, such as ref, className and aria-* attributes.

Part names

Each part's class and state attributes are public and versioned, for an application's CSS to style.

env-top-bar: The top bar.
env-top-bar-actions: The actions at the end.
env-top-bar-loading-bar: The page progress along the bar's bottom edge.
env-top-bar-start: The start of the bar, for a navigation button or a mark.
env-top-bar-title: The title, which truncates first.
data-background: page
data-loading: Present
data-sticky: Present
data-title-bar: Present

Strings

EnvUIProvider's messages overrides each, and a component's own label prop wins over it.

messages.topBar.loading: "Loading page" Names the page progress bar along the bar's bottom edge while a page loads.

Changelog

1.0.0: TopBar, which replaces AppShell.Header and WindowFrame.TitleBar, with sticky, titleBar and loading.
1.0.0-prerelease.6: The loading bar follows the motion tokens: it completes in --env-motion-duration-slow with --env-motion-ease-enter, fades out in --env-motion-duration-fast with --env-motion-ease-exit, and is removed once its fade has ended; at once with durations of 0s.