# AppShell

Places a sticky sidebar beside the main content column.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/AppShell.tsx)

Figma: [Layout/App Shell](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-5593) (`AppShell.Root`), [Layout/Page Header](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-5633) (`AppShell.Header`), [Navigation/Tab Bar](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5265-2292) (`AppShell.Root`)

## Overview

The outer frame of an application. Below 1024px, the sidebar moves into a drawer, which a menu button in a bottom bar opens. With `collapse`, the sidebar collapses to its icons until 768px instead. The bottom bar also repeats the items you choose.

## Examples

### Basic

```tsx
/** Composes the Tempo Wallet shell: the account row, the wallet pages, the theme item and a page header. @module */
import { AppShell, Avatar, Hex, Kbd, Menu, SidebarMenu, StatusChip, style, Surface } from '@tempoxyz/ds'
import { Clock, DarkMode, Home, Link, LogOut, Plus, Wallet } from '@tempoxyz/ds/icons'

export const fill = true
const address = '0x7a3f2c19b0e4d85a6f1c3e9b2d7a40c58e6f91c2'

const balances = ['pathUSD', 'USDC.e', 'AlphaUSD']

export function Demo() {
  return (
    <div {...styles.frame()}>
      <AppShell.Root
        align="start"
        collapse
        style={{ height: '100%', minHeight: 0, overflowY: 'auto' }}
      >
        <AppShell.Sidebar aria-label="Wallet" style={{ height: '100%' }}>
          <AppShell.SidebarHeader>
            <Menu.Root>
              <Menu.Trigger
                render={<SidebarMenu.AccountRow description="Tempo Wallet" label="Piril Akay" />}
              >
                <Avatar size="32">
                  <Avatar.Fallback>PA</Avatar.Fallback>
                </Avatar>
              </Menu.Trigger>
              <Menu.Popup>
                <Menu.Item>
                  <Plus />
                  Add account
                </Menu.Item>
                <Menu.Separator />
                <Menu.Item intent="negative">
                  <LogOut />
                  Sign out
                </Menu.Item>
              </Menu.Popup>
            </Menu.Root>
          </AppShell.SidebarHeader>
          <AppShell.SidebarBody>
            <SidebarMenu.Root>
              <SidebarMenu.Group aria-label="Wallet">
                <SidebarMenu.Item active href="#" tabBar="tab">
                  <Home />
                  Home
                </SidebarMenu.Item>
                <SidebarMenu.Item href="#" tabBar="tab">
                  <Clock />
                  Activity
                </SidebarMenu.Item>
                <SidebarMenu.Item href="#" tabBar="tab">
                  <Wallet />
                  Assets
                </SidebarMenu.Item>
                <SidebarMenu.Item href="#">
                  <Link />
                  Connections
                </SidebarMenu.Item>
              </SidebarMenu.Group>
            </SidebarMenu.Root>
          </AppShell.SidebarBody>
          <AppShell.SidebarFooter>
            <SidebarMenu.Root aria-label="Preferences">
              <SidebarMenu.Item render={<button type="button" />}>
                <DarkMode />
                <span {...styles.grow()}>Dark mode</span>
                <Kbd alt size="small">
                  M
                </Kbd>
              </SidebarMenu.Item>
            </SidebarMenu.Root>
          </AppShell.SidebarFooter>
        </AppShell.Sidebar>
        <AppShell.Main>
          <AppShell.Header>
            <AppShell.Title>Home</AppShell.Title>
            <div {...styles.actions()}>
              <StatusChip intent="positive" network>
                Mainnet
              </StatusChip>
              <Hex.Root size="small" value={address} variant="filled" {...styles.address()}>
                <Hex.Text />
                <Hex.Copy aria-label="Copy wallet address" />
              </Hex.Root>
            </div>
            <AppShell.Trigger />
          </AppShell.Header>
          <div {...styles.list()}>
            {balances.map((balance) => (
              <Surface key={balance}>
                <p {...styles.name()}>{balance}</p>
                <p {...styles.caption()}>Available to send</p>
              </Surface>
            ))}
          </div>
        </AppShell.Main>
      </AppShell.Root>
    </div>
  )
}

namespace styles {
  // The bottom bar takes over below 768px, so the header keeps only its title.
  export const actions = style({
    alignItems: 'center',
    columnGap: '8',
    display: 'flex',
    '@media (max-width: 767px)': { display: 'none' },
  })

  export const address = style({ maxWidth: '10rem !custom' })

  export const caption = style({ color: 'content.secondary', margin: '0', typography: 'body.b3' })

  // The transform makes the frame the containing block for the mobile drawer.
  export const frame = style({
    borderRadius: 'sm',
    height: '32rem !custom',
    overflow: 'hidden',
    transform: 'translateZ(0) !custom',
    selectors: {
      // The maximized gallery preview shows the shell at full window height.
      ':root[data-maximized] &': { borderRadius: '0px !custom', height: '100vh !custom' },
    },
  })

  export const grow = style({ flex: '1 !custom', minWidth: '0 !custom' })

  export const list = style({ display: 'flex', flexDirection: 'column', rowGap: '12' })

  export const name = style({ margin: '0', typography: 'body.b2' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/AppShell/Basic.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { AppShell } from '@tempoxyz/ds'

<AppShell.Root>
  <AppShell.Sidebar>
    <AppShell.SidebarHeader />
    <AppShell.SidebarBody />
    <AppShell.SidebarFooter />
  </AppShell.Sidebar>
  <AppShell.Main>
    <AppShell.Header>
      <AppShell.Title />
    </AppShell.Header>
  </AppShell.Main>
  <AppShell.Trigger />
</AppShell.Root>
```

## Guidelines

### When to Use

* Frame a product with persistent navigation, such as Tempo Console or the web wallet. Render it once, in the root layout.
* Pair a [SidebarMenu](/docs/components/sidebar-menu) with a content column of tables, cards, or settings.

### When Not to Use

* Use [Container](/docs/components/container) for pages without persistent navigation, such as sign-in, onboarding, or a public receipt.
* Use [Dialog](/docs/components/dialog), or a full-screen flow in a [Container](/docs/components/container), for focused tasks such as Send payment.
* Use [Drawer](/docs/components/drawer) for a details or filter panel that opens on demand. The shell's drawer holds only primary navigation.
* Use [Frame](/docs/components/frame) for a header, body, and footer inside a card or popup.

### Plan for Each Layout

The shell switches layouts at 768px and 1024px (the `'768'` and `'1024'` breakpoints). Design and test each.

* **Below 768px (Bottom bar):** The sidebar becomes a drawer from the right edge, and a bottom bar holds the chosen items and the menu button.
* **768px to 1023px (collapse):** The drawer and bottom bar by default. With `collapse`, a 64px column of icons that keep their labels as names.
* **1024px and Up (28px padding):** The sidebar sticks beside the content with its own scroll, and the bottom bar hides.

The drawer is `min(18rem, 85vw)` wide. Server rendering emits the inline sidebar, and CSS hides it below 1024px, or collapses it until 768px with `collapse`.

### Always Render the Trigger

Render `AppShell.Trigger` once inside `AppShell.Root`. It adds the menu button to the end of the bottom bar, so the header keeps its full width for the title and actions.

**Do:** Render the trigger once in the shell.

```tsx
/**
 * Do example for "Always Render the Trigger" on the AppShell page.
 * Render the trigger once in the shell.
 * @module
 */
import { Button, style, Surface } from '@tempoxyz/ds'
import { Menu } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Surface size="small" {...styles.frame()}>
      <span {...styles.title()}>Balances</span>
      <div {...styles.bar()}>
        <Button aria-label="Open menu" shape="icon" size="small">
          <Menu />
        </Button>
      </div>
    </Surface>
  )
}

namespace styles {
  export const bar = style({ display: 'flex', justifyContent: 'flex-end' })

  export const frame = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '24',
    width: '18rem !custom',
  })

  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
}
```

**Don't:** Leave it out. Below 1024px, or 768px with `collapse`, it is the only way to reach every
destination.

```tsx
/**
 * Don't example for "Always Render the Trigger" on the AppShell page.
 * Don't leave it out. Below 1024px, it is the only way to reach navigation.
 * @module
 */
import { style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Surface size="small" {...styles.frame()}>
      <span {...styles.title()}>Balances</span>
      <div {...styles.bar()} />
    </Surface>
  )
}

namespace styles {
  // Matches the height of the bottom bar in the Do example, so only the missing button differs.
  export const bar = style({ minHeight: '32' })

  export const frame = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '24',
    width: '18rem !custom',
  })

  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
}
```

### Choose an Alignment

* **Centered (center):** The default. Centers the sidebar beside a content column up to 1024px wide.
* **Start (start):** Pins the sidebar left, and the content fills the row. Use it for wide data views.

### Structure the Sidebar

* **AppShell.SidebarHeader:** Holds the product or project switcher at the top of the sidebar.
* **AppShell.SidebarBody:** Holds the sidebar menu. It scrolls on its own and fades the edge with more content.
* **AppShell.SidebarFooter:** Holds the account row and other controls, pinned to the bottom edge.

Keep the header and footer short so the menu keeps most of the height. Set `--sidebar-width` to change the width of the wide sidebar.

### Choose the Bottom Bar Items

Wherever the drawer replaces the sidebar, a bottom bar repeats the [SidebarMenu](/docs/components/sidebar-menu) items that set `tabBar`, in sidebar order, and ends with the menu button. Keep the rest in the drawer.

* **Tab (tabBar="tab"):** Shows the icon in the tab bar pill. Choose up to three top destinations.
* **Action (tabBar="action"):** Shows the icon in a floating button beside the pill. Choose one main action.

```tsx
<SidebarMenu.Item active href="/" tabBar="tab">
  <Home />
  Home
</SidebarMenu.Item>
```

### Use One Title per Page

`AppShell.Title` renders the page's `h1` in the header bar across the top of the content column. Keep one primary action in the header.

**Do:** Put the title first, then page actions, such as a `small` [Button](/docs/components/button).

```tsx
/**
 * Do example for "Use One Title per Page" on the AppShell page.
 * Put the title first, then page actions, such as a `small` Button.
 * @module
 */
import { Button, style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Surface size="small" {...styles.frame()}>
      <div {...styles.header()}>
        <span {...styles.title()}>API keys</span>
        <Button size="small">New key</Button>
      </div>
    </Surface>
  )
}

namespace styles {
  export const frame = style({ width: '18rem !custom' })

  export const header = style({ alignItems: 'center', display: 'flex', gap: '12' })

  export const title = style({
    color: 'content.primary',
    flex: '1 !custom',
    typography: 'heading.h3',
  })
}
```

**Don't:** Place actions before the title.

```tsx
/** Don't example for "Use One Title per Page" on the AppShell page. Don't place actions before the title. @module */
import { Button, style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Surface size="small" {...styles.frame()}>
      <div {...styles.header()}>
        <Button size="small">New key</Button>
        <span {...styles.title()}>API keys</span>
      </div>
    </Surface>
  )
}

namespace styles {
  export const frame = style({ width: '18rem !custom' })

  export const header = style({ alignItems: 'center', display: 'flex', gap: '12' })

  export const title = style({
    color: 'content.primary',
    flex: '1 !custom',
    typography: 'heading.h3',
  })
}
```

### Close the Drawer After Navigating

With a client-side router, the drawer stays open when the route changes. Control `AppShell.Root` with `open` and `onOpenChange`, and set `open` to `false` when the location changes.

**Do:** Close the drawer, so the new page shows.

```tsx
/**
 * Do example for "Close the Drawer After Navigating" on the AppShell page.
 * Close the drawer, so the new page shows.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'
import { Menu } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.screen()}>
      <div {...styles.header()}>
        <span {...styles.title()}>API keys</span>
        <Button aria-label="Open menu" shape="icon" size="small" variant="secondary">
          <Menu />
        </Button>
      </div>
      <span {...styles.meta()}>2 active keys</span>
    </div>
  )
}

namespace styles {
  export const header = style({
    alignItems: 'center',
    display: 'flex',
    gap: '12',
    justifyContent: 'space-between',
  })

  export const meta = style({ color: 'content.secondary', typography: 'body.b2' })

  export const screen = style({
    display: 'flex',
    flexDirection: 'column',
    height: '9rem !custom',
    position: 'relative',
    rowGap: '8',
    width: '18rem !custom',
  })

  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
}
```

**Don't:** Leave the drawer over the new page.

```tsx
/**
 * Don't example for "Close the Drawer After Navigating" on the AppShell page.
 * Don't leave the drawer over the new page.
 * @module
 */
import { Button, SidebarMenu, style, Surface } from '@tempoxyz/ds'
import { Home, Key, Menu } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.screen()}>
      <div {...styles.header()}>
        <span {...styles.title()}>API keys</span>
        <Button aria-label="Open menu" shape="icon" size="small" variant="secondary">
          <Menu />
        </Button>
      </div>
      <span {...styles.meta()}>2 active keys</span>
      <Surface size="small" {...styles.drawer()}>
        <SidebarMenu.Root aria-label="Primary" size="small">
          <SidebarMenu.Item href="#">
            <Home />
            Home
          </SidebarMenu.Item>
          <SidebarMenu.Item active href="#">
            <Key />
            API keys
          </SidebarMenu.Item>
        </SidebarMenu.Root>
      </Surface>
    </div>
  )
}

namespace styles {
  export const drawer = style({
    insetBlock: '0 !custom',
    insetInlineEnd: '0 !custom',
    position: 'absolute',
    width: '11rem !custom',
  })

  export const header = style({
    alignItems: 'center',
    display: 'flex',
    gap: '12',
    justifyContent: 'space-between',
  })

  export const meta = style({ color: 'content.secondary', typography: 'body.b2' })

  export const screen = style({
    display: 'flex',
    flexDirection: 'column',
    height: '9rem !custom',
    position: 'relative',
    rowGap: '8',
    width: '18rem !custom',
  })

  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
}
```

## Content

* Match `AppShell.Title` to the label of the active [SidebarMenu](/docs/components/sidebar-menu) item, such as API keys.
* Keep titles short enough to share the header row with its actions at 360px.

## Accessibility

Provides the page landmarks and the `h1`. Below 1024px, the sidebar drawer follows the [WAI-ARIA Dialog (Modal) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/).

### Semantics

* **AppShell.Main (main):** The page's main landmark.
* **AppShell.Header (header):** Holds the menu trigger and the page title.
* **AppShell.Title (h1):** The page's top-level heading.
* **Wide AppShell.Sidebar (complementary):** From 1024px, a landmark named by `aria-label`.
* **Narrow AppShell.Sidebar (dialog):** Below 1024px, a dialog with the same name.
* **AppShell.Trigger (button):** Named "Open menu" or "Close menu" by state.

### Keyboard

* **Move Through the Shell (Tab):** Moves to the trigger, or cycles the open drawer.
* **Open the Drawer (Enter or Space):** Opens the drawer from the trigger.
* **Close the Drawer (Escape):** Closes the drawer.

### Focus

* **Opening (Tab or Shift+Tab):** The drawer is modal. Opening it moves focus inside and traps it.
* **While Open (aria-hidden):** Hides the rest of the page, including the trigger, from assistive technology.
* **Closing:** Escape, the backdrop, or a swipe right closes the drawer and returns focus to the trigger.

### Motion and Size

* **Reduced Motion (prefers-reduced-motion):** The drawer fades, and the trigger switches instantly.
* **Minimum Width (360px):** The shell never shrinks below this width.

### Your Responsibilities

* **Name the Sidebar (aria-label):** Name the sidebar, such as "Primary". The name labels the landmark and the drawer.
* **Use One Title (h1):** Use one page title. Start the headings of the content at `h2`.
* **Add a Skip Link (SC 2.4.1):** If the sidebar holds many links, add a [skip link](https://www.w3.org/WAI/WCAG22/Understanding/bypass-blocks.html). The shell adds none.

## Related

[SidebarMenu](/docs/components/sidebar-menu)

Use for the navigation inside the sidebar.

[Container](/docs/components/container)

Use for pages without a sidebar.

[Drawer](/docs/components/drawer)

Use for panels that open on demand.

[Responsive Layout](/docs/patterns/responsive-layout)

Covers adapting pages across breakpoints.

[Navigation](/docs/patterns/navigation)

Covers choosing between navigation components.
