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>} />}
/>
);
}Tools before the search, PR theme
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.
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.
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.
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.
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
- Menu button (phone, inside
AppShellonly): a 44px circle with a menu icon; opensMobileNavSheet. - 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.
- Breadcrumbs (
- Tools (
.kit-shell-tools, gap 10), in this order:leading→search→LanguageToggle(withonToggleLanguage) →actions→userMenu.
Variants
| Use | Props | Look |
|---|---|---|
| Brand dashboard | title, subtitle, search, onToggleLanguage, actions (help TopbarMenu, NotificationsMenu), userMenu | The brand mock. |
| PR Portal deep page | breadcrumbs, title, leading (e.g. "Record gifts for a brand"), search, actions (bell, "+ New") | The PR mock. |
| Bare | title (and subtitle) only | Sign-in, error pages, embedded views. |
| Phone (<600px) | automatic | Title 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) | automatic | Tools take a row of their own under the title. |
States
| State | How |
|---|---|
| Long title / subtitle | Title 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 open | The menu button has aria-expanded="true". |
| Focus | Tools 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
- Every Brand dashboard screen (Home, Find creators, Creators, Coupons, Motivation, Payments, Analytics, Settings). Screens: Home … Settings.
- Every PR Portal screen; breadcrumbs on brand detail and campaign pages. Screens: PR · Home, PR · Brand, PR · Affiliate programs.
Guidelines
Do
- Use one
AppHeaderper 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>withtitleIdforaria-labelledby.- Breadcrumbs are a
<nav aria-label="Breadcrumb">; crumb links get a 44px tall hit area on touch tiers (≤1024px; a padding/margin trick inshell.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.
Related
AppShell: the frame it sits in.HeaderSearch,LanguageToggle,TopbarMenu,UserMenu,NotificationsMenu: its tools.MobileNavSheet: opened by its phone menu button.
See also: useAppShell · useLanguage · Avatar · Button · Icon · BrandAvatar · LogoutButton
Source
src/shell/AppHeader.tsx (line 52) on GitHub.