Skip to Content
BBRICKSv0.7.4
ShellGuide

Build an app frame

Compose AppShell, the sidebar, the header, search and menus into a dashboard frame.

The shell is the dashboard frame: a sidebar, a top bar and the content area, with the phone and tablet layouts built in. Everything specific to your app (the navigation items, the brand, the words, the URLs, the search function, the current route) comes in as props. Nothing in it fetches, routes or reads your types.

A whole app frame

Sidebar, header and content area; the sidebar becomes an icon rail on tablets and a bottom bar with a "More" sheet on phones. The frame here is contained and sized to a desktop.

Code
import { useState } from 'react';
import { AppHeader, AppShell, Button, Card, SidebarCard, useLanguage, type NavItem } from '@ergasti/bricks';
import { brandMark, brandNav } from './nav';

function Frame() {
  const language = useLanguage();
  const [active, setActive] = useState('home');
  const item = brandNav.flatMap((g) => g.items).find((i) => i.id === active);
  const title = item ? (typeof item.label === 'string' ? item.label : item.label[language]) : '';
  return (
    <AppShell
      brand={brandMark}
      nav={brandNav}
      activeId={active}
      onNavigate={(next: NavItem) => setActive(next.id)}
      header={<AppHeader title={title} subtitle={language === 'ar' ? 'اللي مستنيك النهارده' : 'What needs you today'} />}
      sidebarCard={<SidebarCard title={language === 'ar' ? 'محتاج مساعدة؟' : 'Need a hand?'} action={<Button size="sm">{language === 'ar' ? 'كلّم TRNDR' : 'Contact TRNDR'}</Button>}>{language === 'ar' ? 'مدير حسابك بيتابع معاك.' : 'Your account manager handles approvals for you.'}</SidebarCard>}
    >
      <Card><Card.Header title={title} sub="The page content goes here." /></Card>
    </AppShell>
  );
}

The parts

You giveIt draws
brand (ShellBrand: name, label, optional mark and tagline)The logo block at the top of the sidebar and the phone sheet
nav (NavGroup[])The sidebar, the icon rail, the phone tab bar and the "More" sheet, all from one tree
activeId and onNavigate(item)The highlighted item; called for a pick anywhere (the shell closes its overlays first)
header (an AppHeader)The top bar above <main>
sidebarCard, sidebarFooter, sheetFooterA help card, the signed-in user, the phone sheet's contact and sign-out
childrenThe current screen, inside <main id={mainId}>

The navigation tree

A NavGroup has an id, optional heading, collapsible, and items. A NavItem has an id, a label (a string or { en, ar }), an optional icon (a kit icon name or any node), count, hot (a count that should draw attention), badge (new or soon), href or onSelect, disabled and indent.

const nav: NavGroup[] = [
  { id: 'main', items: [
    { id: 'home', label: { en: 'Home', ar: 'الرئيسية' }, icon: 'home' },
    { id: 'creators', label: { en: 'Creators', ar: 'صنّاع المحتوى' }, icon: 'creators', count: 304 },
  ] },
  { id: 'more', collapsible: true, heading: { en: 'More', ar: 'المزيد' }, items: [
    { id: 'fraud', label: { en: 'Fraud checks', ar: 'فحص الاحتيال' }, icon: 'flag', count: 1, hot: true },
  ] },
];

flattenNav(groups) returns every item in order; labelText(label, language) resolves a label.

Routing

The shell does not route. Wire activeId to your router and call it from onNavigate:

const location = useLocation();
const navigate = useNavigate();
<AppShell
  brand={brand}
  nav={nav}
  activeId={activeIdFor(location.pathname)}
  onNavigate={(item) => navigate(`/${item.id}`)}
  routeKey={location.pathname}   // focus moves to <main> when this changes
>

routeKey defaults to activeId. When it changes, focus moves to <main>, so a screen reader starts at the new view. The skip link ("Skip to content") also focuses <main> without touching the URL, so an app that keeps its view in the hash does not lose it.

Three layouts, one tree

Window widthLayout
over 1024pxThe full sidebar
860 to 1024pxAn icon rail that expands as an overlay
under 860pxA tab bar with the first four enabled items that have an icon (or bottomNavIds) and a "More" sheet with the whole tree

The tier follows the window; pass tier to force one (tests, previews, server rendering). useAppShell() inside the shell tells a component its tier and whether the sheet is open. The examples on these pages are drawn in contained frames, so the shell inside them follows the window, not the frame.

The header

AppHeader takes a title, an optional subtitle and breadcrumbs, a search slot, an actions slot, a userMenu slot and an onToggleLanguage that shows the language switch. Put HeaderSearch, NotificationsMenu and TopbarMenu in the slots:

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>} />}
    />
  );
}

HeaderSearch calls your fetcher(term, signal) after a pause and groups what comes back; it knows nothing about your API. See HeaderSearch.

Protect screens, show usage, handle "coming soon"

Wrap each screen in ScreenErrorBoundary with resetKey set to the route, so one screen's crash does not blank the app and navigating away clears it. Use UsageMeter for capacity (seats, a plan limit) and EmptyView for a screen that is not built yet:

Contain a screen's crash

A render error inside shows a "Something went wrong" panel with a reload button instead of a blank page; resetKey (the route) clears it when you navigate away. Press the button. (React logs the error to the console; that is expected.)

Code
import { useState } from 'react';
import { Button, Card, ScreenErrorBoundary } from '@ergasti/bricks';

function Crashy() {
  const [crash, setCrash] = useState(false);
  if (crash) throw new Error('Example crash');
  return <Button size="sm" onClick={() => setCrash(true)}>Crash this card</Button>;
}

function Boundary() {
  return (
    <ScreenErrorBoundary resetKey="docs" onError={() => {}}>
      <Card><Card.Header title="A screen" actions={<Crashy />} /></Card>
    </ScreenErrorBoundary>
  );
}

Language

AppShell takes its language from the provider unless you pass language, and sets dir and lang on its own root. To switch language, flip the language you give your BricksProvider (and persist it). The shell's own words (menu, close, skip link, "More") come from SHELL_COPY and can be overridden with the copy prop.

Server rendering

AppShell reads the window width on its first render in the browser. On the server pass tier, for example tier="desktop"; it is the first value (the server render does not touch window) and it pins the shell to that tier while it is set. See Browser support and SSR.

Components

Every shell component has its own page in the sidebar: AppShell, Sidebar, NavGroups, BottomNav, MobileNavSheet, AppHeader, HeaderSearch, TopbarMenu, UserMenu, UsageMeter, EmptyView and ScreenErrorBoundary.

flattenNav

function

Every item of every group, in order.

function flattenNav(groups: readonly NavGroup[]): NavItem[]

Prop

Type

Source: src/shell/types.ts (line 51)

labelText

function

The label in language.

function labelText(label: NavLabel, language: Lang): string

Prop

Type

Source: src/shell/types.ts (line 9)

On this page