Skip to Content
BBRICKSv0.7.4
ShellHeader and menus

AppHeader

The mock's .topbar: h1 + subtitle (breadcrumbs above when given), then .tools. Inside an AppShell on a phone, a menu button leads and opens the nav sheet. The one banner landmark of the page. Under 860px the tools take a row of their own; it never wraps (it scrolls sideways when it must), and under 600px a HeaderSearch folds into a search button that opens it over the row.

import { AppHeader } from '@ergasti/bricks';

Examples

Header

A page title and subtitle (breadcrumbs above), a search slot, a slot for menus, the language toggle and a user menu. On phones the title shrinks and the menus stay in reach.

Code
import { useState } from 'react';
import { AppHeader, Avatar, NotificationsMenu, UserMenu, useLanguage, type NotificationItem } from '@ergasti/bricks';

function Page() {
  const language = useLanguage();
  const [items, setItems] = useState<NotificationItem[]>([
    { id: 1, text: <>TRNDR approved <b>Karim Hosny</b>’s join request.</>, when: '2 hours ago', icon: 'user', tone: 'lime', unread: true },
    { id: 2, text: <>Your wallet is <b>low (17% left)</b>.</>, when: 'Today', icon: 'wallet', tone: 'rasp', unread: true },
  ]);
  return (
    <AppHeader
      title={language === 'ar' ? 'المدفوعات' : 'Payments'}
      subtitle={language === 'ar' ? 'محفظتك والعمولات' : 'Your wallet, commissions and payouts'}
      onToggleLanguage={() => {}}
      actions={<NotificationsMenu items={items} onOpenItem={(id) => setItems((all) => all.map((n) => (n.id === id ? { ...n, unread: false } : n)))} onMarkAllRead={() => setItems((all) => all.map((n) => ({ ...n, unread: false })))} onSeeAll={() => {}} />}
      userMenu={<UserMenu name="Nour Hassan" detail="HushUp" avatar={<Avatar name="Nour Hassan" seed={3} size="sm" />} logout={<button type="button">Sign out</button>} />}
    />
  );
}

leading draws a screen's own tools first, as the PR mock puts a screen's own tools ("Record gifts for a brand") before its search; actions (the bell) stay after it. The breadcrumb link takes the theme's look: raspberry, 600, no underline (the brand theme keeps the crumb colour, underlined); on touch screens it is a 44px tall target.

Pinned to TRNDR presetPR theme
Code
import { AppHeader, Button, HeaderSearch, Icon, NotificationsMenu, type NotificationItem } from '@ergasti/bricks';

const PR_NOTES: NotificationItem[] = [{ id: 1, text: <><b>Glow Lab</b> requested a challenge.</>, when: 'Today', icon: 'flag', tone: 'butter', unread: true }];

function ToolsBeforeSearch() {
  return (
    <AppHeader
      title="GS-0017 · Glow Lab"
      subtitle="For December glow"
      breadcrumbs={<><a href="#gifts">Gift stock</a> / GS-0017</>}
      leading={<Button variant="ghost"><Icon name="gift" />Record gifts for a brand</Button>}
      search={<HeaderSearch placeholder="Search brands, creators…" fetcher={async () => []} onSelect={() => {}} />}
      actions={<NotificationsMenu items={PR_NOTES} onOpenItem={() => {}} onMarkAllRead={() => {}} onSeeAll={() => {}} />}
    />
  );
}

The phone header

Under 860px the tools take one row of their own under the title and never wrap (the row scrolls sideways if it must); under 600px the search folds into a 44px search button that opens the box over the row (Escape on the empty box, or tapping elsewhere, folds it back), and the raspberry "+ New" shows its icon only. Open this page on a phone, or narrow the window, to see it fold. Pass collapsible={false} to HeaderSearch to keep the pill at every width.

Pinned to TRNDR presetPR theme
Code
import { AppHeader, HeaderSearch, Icon, NotificationsMenu, TopbarMenu, type NotificationItem } from '@ergasti/bricks';

const PR_NOTES: NotificationItem[] = [{ id: 1, text: <><b>Glow Lab</b> requested a challenge.</>, when: 'Today', icon: 'flag', tone: 'butter', unread: true }];

function PhoneHeader() {
  return (
    <div style={{ maxWidth: 390 }}>
      <AppHeader
        title="Gift stock"
        subtitle="Brands send gifts to the warehouse and tell us what they sent."
        search={<HeaderSearch placeholder="Search brands, creators…" fetcher={async () => []} onSelect={() => {}} />}
        actions={<>
          <NotificationsMenu items={PR_NOTES} onOpenItem={() => {}} onMarkAllRead={() => {}} onSeeAll={() => {}} />
          <TopbarMenu label="New" variant="pill" tone="rasp" trigger={<><Icon name="plus" />New</>} items={[{ id: 'gift', label: 'Gift stock', icon: 'gift' }]} />
        </>}
      />
    </div>
  );
}

Leading tools and a clamped phone subtitle, PR theme

leading holds the screen's own tools and draws them before the search, while actions (the bell, "+ New") stay after it: the PR mock's order. Under 600px a leading Button with an icon shows only the icon (its words stay its accessible name), and subtitleLines={2} clamps the subtitle to two lines with an ellipsis (the full text stays readable to screen readers and is the tooltip). Narrow the window to see both.

Pinned to TRNDR presetPR theme
Code
import { AppHeader, Button, HeaderSearch, Icon, NotificationsMenu, TopbarMenu, type NotificationItem } from '@ergasti/bricks';

const PR_NOTES: NotificationItem[] = [{ id: 1, text: <><b>Glow Lab</b> requested a challenge.</>, when: 'Today', icon: 'flag', tone: 'butter', unread: true }];

function LeadingTools() {
  return (
    <AppHeader
      title="Gift stock"
      subtitle="Brands send gifts to the warehouse and tell us what they sent. Nothing counts as gift stock until you confirm what arrived."
      subtitleLines={2}
      leading={<Button><Icon name="plus" />Record gifts for a brand</Button>}
      search={<HeaderSearch placeholder="Search brands, creators…" fetcher={async () => []} onSelect={() => {}} />}
      actions={<>
        <NotificationsMenu items={PR_NOTES} onOpenItem={() => {}} onMarkAllRead={() => {}} onSeeAll={() => {}} />
        <TopbarMenu label="New" variant="pill" tone="rasp" trigger={<><Icon name="plus" />New</>} items={[{ id: 'gift', label: 'Gift stock', icon: 'gift' }]} />
      </>}
    />
  );
}

A brand page's title, PR theme

titleLead draws a big square avatar in the h1 before the name, 14px from it and centred on its line; it is decorative, so the heading still reads "Glow Lab". The breadcrumb sits above it and the page's own tool ("View as brand") leads the tools row.

Pinned to TRNDR presetPR theme
Code
import { AppHeader, BrandAvatar, Button, HeaderSearch, Icon } from '@ergasti/bricks';

function BrandTitle() {
  return (
    <AppHeader
      title="Glow Lab"
      titleLead={<BrandAvatar name="Glow Lab" color="#C7325C" size="lg" />}
      breadcrumbs={<><a href="#brands">Brands</a> / Glow Lab</>}
      leading={<Button><Icon name="eye" />View as brand</Button>}
      search={<HeaderSearch placeholder="Search brands, creators…" fetcher={async () => []} onSelect={() => {}} />}
    />
  );
}

Props

Prop

Type

Design guidance

How the BRICKS design system uses AppHeader. Written in docs/content/components/AppHeader.md; the props above are read from the code, which wins where the two disagree.

The page's top bar: the h1 title with a subtitle (or breadcrumbs above it), then a row of tools (screen tools, the search pill, the language circle, help, the bell, a "New" menu, the user menu); use it once at the top of every dashboard screen, inside AppShell.

It is both mocks' .topbar. Brand dashboard: title and subtitle, then search "Search creators, coupons…", the "عربي" language circle, help and the notifications bell. PR Portal: breadcrumbs ("Brands / Mira Beauty") when deep, screen tools first, then search "Search brands, creators…", the bell and a raspberry "+ New" menu. It is the page's one banner landmark. Inside an AppShell on a phone a menu button leads it and opens the nav sheet.

Anatomy

  1. Menu button (phone, inside AppShell only): a 44px circle with a menu icon; opens MobileNavSheet.
  2. Title block (.kit-shell-top-title):
    • Breadcrumbs (.kit-shell-crumb, 13px --ink-3, in a <nav aria-label="Breadcrumb">).
    • <h1>: display face, 800, --shell-title-size (30px; 22px on phones); Cairo in Arabic.
    • Subtitle (.kit-shell-top-sub, --ink-3, max 620px), optionally clamped on phones.
  3. Tools (.kit-shell-tools, gap 10), in this order: leading → search → LanguageToggle (with onToggleLanguage) → actions → userMenu.

Variants

UsePropsLook
Brand dashboardtitle, subtitle, search, onToggleLanguage, actions (help TopbarMenu, NotificationsMenu), userMenuThe brand mock.
PR Portal deep pagebreadcrumbs, title, leading (e.g. "Record gifts for a brand"), search, actions (bell, "+ New")The PR mock.
Baretitle (and subtitle) onlySign-in, error pages, embedded views.
Phone (<600px)automaticTitle 22px; tools on their own row that scrolls sideways; HeaderSearch folds to a button; a kit Button with an icon in leading shows the icon only.
Tablet (<860px)automaticTools take a row of their own under the title.

States

StateHow
Long title / subtitleTitle wraps; subtitleLines={2} clamps the subtitle on phones with an ellipsis (the full string is its tooltip and stays readable to screen readers).
Search expanded (phone)The folded HeaderSearch opens over the tools row; the other tools hide.
Nav sheet openThe menu button has aria-expanded="true".
FocusTools use the circle focus style: raspberry border + focus ring.

Usage

// Brand › Home
<AppHeader
  title="Home"
  subtitle="What needs you today, and what the program earned"
  search={<HeaderSearch placeholder="Search creators, coupons…" fetcher={search} groupLabels={{ creators: 'Creators', coupons: 'Coupons' }} onSelect={open} />}
  onToggleLanguage={toggleLanguage}
  actions={<>
    <TopbarMenu label="Help" trigger={<Icon name="help" />} items={helpItems} />
    <NotificationsMenu items={notifications} onOpenItem={openNotification} onMarkAllRead={markAllRead} onSeeAll={seeAll} />
  </>}
  userMenu={<UserMenu name="Nour Hassan" detail="HushUp" avatar={<Avatar name="Nour Hassan" seed={3} size="sm" />} logout={<LogoutButton onLogout={signOut}>Sign out</LogoutButton>} />}
/>
// PR Portal › a brand's page: breadcrumbs, a screen tool before the search
<AppHeader
  breadcrumbs={<><a href="/brands">Brands</a> / Mira Beauty</>}
  title="Mira Beauty"
  leading={<Button><Icon name="plus" />Record gifts for a brand</Button>}
  search={<HeaderSearch placeholder="Search brands, creators…" fetcher={search} onSelect={open} />}
  actions={<NotificationsMenu items={notifications} onOpenItem={openNotification} onSeeAll={seeAllNotifications} />}
/>
import { AppHeader, AppShell, KpiGrid, Tile, type NavGroup, type ShellBrand } from '@ergasti/bricks';

declare const nav: NavGroup[];
declare const brand: ShellBrand;

// Composition: the header in the shell's header slot, above the page content
export function HomePage({ toggle }: { toggle: () => void }) {
  return (
    <AppShell nav={nav} activeId="home" brand={brand}
      header={<AppHeader title="Home" subtitle="What needs you today, and what the program earned" onToggleLanguage={toggle} />}>
      <KpiGrid>
        <Tile tone="lime" label="Sales" value="EGP 312,400" />
        <Tile tone="sky" label="Orders" value="1,284" />
      </KpiGrid>
    </AppShell>
  );
}

Where it appears

Guidelines

Do

  • Use one AppHeader per page; its <h1> is the page title.
  • Keep the subtitle to one sentence that says what the page is for.
  • Keep the mock's tool order: screen tools, search, language, help, bell, New, user.

Don't

  • Don't put more than one primary (raspberry) button in the tools.
  • Don't put page filters here; they belong in the page's Toolbar / ListToolbar.
  • Don't add a second header inside the content.

RTL and Arabic

  • The title block is on the right and the tools on the left in Arabic; the title switches to Cairo with no letter-spacing.
  • The language circle shows "EN" in Arabic, "عربي" in English.
  • Breadcrumb separators stay " / "; crumb text follows the page direction.

Tokens

--shell-title-size, --font-family-display, --ink, --ink-3, --lh-ar, --line, --card, --rasp (focus border), --focus-ring, --color-control-border-hover, --radius-xs; breadcrumbs: --shell-crumb-link, --shell-crumb-weight, --shell-crumb-deco (themed per dashboard).

Accessibility

  • <header>: the page's single banner landmark; <h1> with titleId for aria-labelledby.
  • Breadcrumbs are a <nav aria-label="Breadcrumb">; crumb links get a 44px tall hit area on touch tiers (≤1024px; a padding/margin trick in shell.css); on desktop they are plain 13px text links.
  • Phone menu button: aria-label="Menu", aria-haspopup="dialog", aria-expanded.
  • Tools are 44px circles; the row never wraps on phones, it scrolls sideways.
  • A clamped subtitle is clipped visually only.

Found in the source

  • ARIA attributes set: aria-label, aria-haspopup, aria-expanded, aria-hidden.
  • Its tests cover: “puts breadcrumbs above the title in a labelled nav, and gives the h1 the id asked for”; “touch tiers: the search field and the breadcrumb links are 44px tall targets”; “names the other language in that language and toggles with the keyboard”.

Read from the component's source and tests. See Accessibility for the patterns the library follows.

See also: useAppShell · useLanguage · Avatar · Button · Icon · BrandAvatar · LogoutButton

Source

src/shell/AppHeader.tsx (line 52) on GitHub.

On this page