AppShell

When to use

AppShell is the frame of a multi-page app that stays the same on every page: the sidebar, the top bar and the content area. Use it once at the root of the app; pages only change the content.

When not to use

• For single-page flows: Hide the frame in sign-in, sign-up or step-by-step flows so nothing distracts.
• For navigation inside a page: Use Tabs or a list of links.
• Inside a narrow panel: AppShell fills the screen height; do not nest it.

Anatomy

Skip to content

Product name

General

HomeInbox 3Reports

Administration

TeamSettings

Home

Page content sits here.

LightDark

Copy code

import { AppShell, NavGroup, NavItem, PageHeader, Provider } from '@bigbang/ui';

export default function Default() {
  return (
    <Provider locale="en-GB">
      <AppShell
        mainId="default-example-main"
        className="h-[28rem] min-h-0"
        brand={<strong>Product name</strong>}
        nav={
          <>
            <NavGroup label="General">
              <NavItem href="#" label="Home" icon="home" current />
              <NavItem href="#" label="Inbox" icon="mail" badge={3} />
              <NavItem href="#" label="Reports" icon="layout-grid" />
            </NavGroup>
            <NavGroup label="Administration" collapsible>
              <NavItem href="#" label="Team" icon="user" />
              <NavItem href="#" label="Settings" icon="settings" />
            </NavGroup>
          </>
        }
      >
        <PageHeader title="Home" description="Page content sits here." />
      </AppShell>
    </Provider>
  );
}

1. Skip link: Shows when it gets keyboard focus.
2. Sidebar: Product name, groups and links; a sliding indicator next to the current page.
3. Collapse button: Narrows the sidebar to icons and widens it again.
4. Top bar: The menu button below 1024 px and the header content.
5. Content: The main region; it usually starts with a PageHeader.
6. Menu drawer: Replaces the sidebar below 1024 px.

Behaviour

• The current page is marked with current: the selected fill, a brand-coloured icon and the bar on the left. When the page changes, the bar slides on a spring; on first render it appears in place without sliding.
• The collapse button narrows the sidebar to 48 px (Ctrl+B or Cmd+B, or a click on the sidebar edge, does the same); labels hide but stay as browser tooltips and for screen readers. When it widens, labels fade back in. The width change is not animated (MOT-02).
• Clicking the heading of a collapsible group opens and closes it; the content fades in and drops 4 px, the chevron turns half a turn.
• Below 1024 px the sidebar hides. The menu button slides the drawer in from the side and dims the backdrop. Clicking a link, Escape or a click outside closes the drawer and focus returns to the menu button.
• With reduced motion the indicator moves at once and the drawer only fades.

Guidelines

• Use at most two levels in the sidebar: group and link.
• Give every link an icon; the narrow sidebar makes items without icons unrecognisable.
• Keep a group under seven links; make rarely used groups collapsible.
• Keep few items in the top bar, such as search (a button that opens Command) and the user menu.

Content

• Link labels are the page name, one or two words.
• Group headings are short noun phrases.

Turkish	English
Ana menü	Main menu
İçeriğe geç	Skip to content
Menüyü aç	Open menu
Menüyü kapat	Close menu
Menüyü daralt	Collapse menu
Menüyü genişlet	Expand menu

Glass

Under a Provider material="glass", the top bar turns glass with a blurred scroll edge under it, and in the inset variant so does the sidebar. The content panel and the menu drawer stay solid. material="solid" keeps it solid.

Related components

• PageHeader: The top of the content area.
• Breadcrumbs: Location on deep pages.
• Command: Quick navigation from the keyboard.