Skip to Content
BBRICKSv0.7.4
ShellFrame

AppShell

The dashboard frame: skip link, the sidebar slot (which keeps its width while the aside itself is fixed to the viewport), the main column (header, then <main>), and the phone tab bar + nav sheet. Three tiers (decision Q4): >1024 full sidebar, 860–1024 a 72px icon rail that expands over the content (Escape or the scrim closes it), <860 no sidebar: a tab bar, the header's menu button and a modal sheet (with the sidebar's card and user row, so they stay reachable). Picking a destination closes every overlay. No routing, fetching or app types inside: the nav is data and onNavigate reports the pick.

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

Examples

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

Props

Prop

Type

Design guidance

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

The dashboard frame: skip link, the dark sidebar (or icon rail, or phone tab bar and nav sheet), the header slot and the <main> region; use it once at the root of every Brand dashboard and PR Portal screen.

It is both mocks' .app layout: a fixed 252px dark sidebar (248px in the PR theme) beside a main column with the top bar and the page. It adapts across three tiers (decision Q4): above 1024px the full sidebar; 860–1024px a 72px icon rail that expands over the content; under 860px no sidebar, a bottom tab bar, a menu button in the header and a modal nav sheet. It does no routing or fetching: the nav is data and onNavigate reports the pick.

Anatomy

  1. Skip link (.kit-shell-skip): "Skip to main content", visible on focus, moves focus to <main> without touching the URL.
  2. Sidebar slot (.kit-shell-slot): reserves the sidebar width while the Sidebar itself is fixed to the viewport (top to bottom, scrolls on its own).
  3. Main column (.kit-shell-col, padding --shell-main-pad, 24px 32px 56px): the header (AppHeader), then <main id="main-content" tabIndex={-1}> (.kit-shell-main, a 16px-gap column).
  4. Tablet: the rail, its expand/collapse toggle and, while expanded, a scrim.
  5. Phone: BottomNav (fixed, 64px) and MobileNavSheet.

Variants

TierWidthNavigationHow to get it
desktop> 1024pxFull sidebar with brand, nav, sidebarCard, sidebarFooterAutomatic, or tier="desktop".
tablet860–1024px72px icon rail; toggle expands it over the content (shadow, scrim; Escape or the scrim closes)Automatic, or tier="tablet".
mobile< 860pxBottom tab bar (four items + More), header menu button, nav sheet with sheetFooterAutomatic, or tier="mobile".
PR Portal look—248px sidebar, PR nav coloursWrap in data-bricks-theme="pr".

States

StateHow
Active destinationactiveId (the item gets aria-current="page").
Route changeWhen routeKey (default activeId) changes, focus moves to <main> (not on first render).
Rail expandedTablet toggle; picking an item or leaving the tier collapses it.
Sheet openPhone menu button or More; picking an item closes it. Leaving the tier closes it.
Empty screenRender EmptyView as the children (story EmptyScreen).

Types

ShellBrand (brand): { mark?, name, label, tagline? }: the sidebar's brand block and the sheet's title.

ViewportTier (tier): 'desktop' | 'tablet' | 'mobile'.

Usage

const nav: NavGroup[] = [
  { id: 'main', items: [
    { id: 'home', label: { en: 'Home', ar: 'الرئيسية' }, icon: 'home' },
    { id: 'find', label: { en: 'Find creators', ar: 'اكتشف صنّاع المحتوى' }, icon: 'find', badge: { label: { en: 'NEW', ar: 'جديد' }, tone: 'new' } },
    { id: 'creators', label: { en: 'Creators', ar: 'صنّاع المحتوى' }, icon: 'creators', count: 304 },
    { id: 'coupons', label: { en: 'Coupons', ar: 'الكوبونات' }, icon: 'coupons', count: 304 },
    { id: 'motivation', label: { en: 'Motivation', ar: 'التحفيز' }, icon: 'motivation', count: 2 },
    { id: 'payments', label: { en: 'Payments', ar: 'المدفوعات' }, icon: 'payments' },
    { id: 'analytics', label: { en: 'Analytics', ar: 'التحليلات' }, icon: 'analytics' },
    { id: 'log', label: { en: 'Activity log', ar: 'سجل النشاط' }, icon: 'log' },
    { id: 'settings', label: { en: 'Settings', ar: 'الإعدادات' }, icon: 'settings' },
  ] },
];

<BricksProvider preset={trndrPreset} language={language}>
  <AppShell
    brand={{ name: <>TRNDR<span className="kit-shell-accent">.</span>HushUp</>, label: 'TRNDR.HushUp', tagline: 'Brand dashboard' }}
    nav={nav}
    activeId={route}
    onNavigate={(item) => navigate(`/${item.id}`)}
    header={<AppHeader title="Home" subtitle="What needs you today, and what the program earned" onToggleLanguage={toggle} />}
    sidebarCard={<SidebarCard title="Need a hand?" action={<Button size="sm">Contact TRNDR</Button>}>Your TRNDR account manager handles approvals, coupons and payouts for you.</SidebarCard>}
    sheetFooter={<LogoutButton onLogout={signOut}>Sign out</LogoutButton>}
  >
    <KpiGrid>…</KpiGrid>
    <div className="scr-grid scr-grid--2">…</div>
  </AppShell>
</BricksProvider>
import { AppHeader, AppShell, Avatar, Icon, LogoutButton, SidebarUser, type NavGroup, type NavItem, type ShellBrand } from '@ergasti/bricks';

declare const PR_NAV: NavGroup[];
declare const prBrand: ShellBrand;

// PR Portal: the theme, a nav with headings and indented children, a user row at the bottom
export function PrFrame({ go, signOut, children }: { go: (item: NavItem) => void; signOut: () => void; children: React.ReactNode }) {
  return (
    <div data-bricks-theme="pr">
      <AppShell brand={prBrand} nav={PR_NAV} activeId="challenges" onNavigate={go}
        header={<AppHeader breadcrumbs={<><a href="/programs">Campaigns</a> / Challenges</>} title="Challenges" />}
        sidebarFooter={<SidebarUser avatar={<Avatar name="Mona Adel" seed={1} size="sm" />} name="Mona Adel" detail="PR team"
          action={<LogoutButton className="kit-shell-me-out" onLogout={signOut}><Icon name="logout" /><span className="kit-sr">Sign out</span></LogoutButton>} />}>
        {children}
      </AppShell>
    </div>
  );
}

Where it appears

Guidelines

Do

  • Keep the nav as data; route in onNavigate.
  • Pass header rather than rendering AppHeader inside the children, so it sits above <main>.
  • Give every top-level item an icon, so the rail and tab bar have glyphs.
  • Use routeKey when the view changes without activeId changing (a drawer route, a tab).

Don't

  • Don't nest shells or put the shell in a scrolling container: the sidebar and tab bar are fixed to the viewport.
  • Don't put more than four items in bottomNavIds.
  • Don't hide nav items per tier; the sheet always has the whole nav.

RTL and Arabic

  • language="ar" sets dir="rtl" and lang="ar" on the frame: the sidebar moves to the right, the sheet slides from the right, the rail toggle glyph mirrors.
  • Nav labels take { en, ar }; headings drop uppercase and letter-spacing in Arabic.

Tokens

--sidebar-width-desktop (252px; PR 248px), --sidebar-width-rail (72px), --bottom-nav-height (64px), --shell-main-pad, --shell-top-offset, --shell-side-bg / --color-sidebar, --shell-side-ink, --shadow-drawer, --card, --ink, --rasp (skip link border).

Accessibility

  • Landmarks: the sidebar <nav aria-label="Sidebar navigation">, the header's <header>, <main>, and on phones <nav aria-label="Bottom navigation">.
  • Skip link first in tab order; focus moves to <main> on route change so screen readers start at the new view.
  • The phone sheet is a modal dialog (focus trap, Escape, the page behind inert); the tablet rail closes on Escape.
  • Nav items, sign-out and menu items are at least 44px tall on touch tiers (≤1024px). On desktop, nav items are about 42px (11px padding + a 14px × 1.45 line; about 40px in the PR theme, 10px padding).

Found in the source

  • ARIA attributes set: aria-label.
  • Keys the code handles: Escape.
  • It moves focus in code.
  • Its tests cover: “closes the expanded rail on Escape and on the scrim”; “has a skip link to the one main landmark, and following it focuses main without touching the hash”; “moves focus to main on a route change, not on the first render”; “routeKey drives the focus move when the route is finer than the nav item (a tab inside a screen)”.

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

See also: useViewportTier · useLanguage · SidebarCard · Button · Card · BrandMark

Source

src/shell/AppShell.tsx (line 59) on GitHub.

On this page