Skip to main content

AppShell

Lays out header, sidebar, main, and optional aside as one responsive app frame.

import { AppShell } from "@/fragments/ui";Source

Preview

import { ChartBar, Gear, House } from '@phosphor-icons/react';
import { AppShell } from '@/components/AppShell';
import { Box } from '@/components/Box';
import { Header } from '@/components/Header';
import { Icon } from '@/components/Icon';
import { Sidebar } from '@/components/Sidebar';

Installation

npx @usefragments/cli add appshell

Writes src/fragments/ui/components/AppShell plus what it imports, the globals stylesheet, and .fragments/registry-lock.json, then prints the packages to add. No account, no key.

Your own registry: publish from Fragments Cloud and add --registry org/name. Connect a workspace.

Anatomy

AppShell is a compound: import the root and reach its parts through dot notation.

  • AppShell.Header
  • AppShell.Sidebar
  • AppShell.Main
  • AppShell.Aside

Header spans the full width above the sidebar.

import { ChartBar, Gear, House } from '@phosphor-icons/react';
import { AppShell } from '@/components/AppShell';
import { Box } from '@/components/Box';
import { Header } from '@/components/Header';
import { Icon } from '@/components/Icon';
import { Sidebar } from '@/components/Sidebar';
import { Stack } from '@/components/Stack';
import { Text } from '@/components/Text';
import { ThemeToggle } from '@/components/Theme';

<Box height="360px" overflow="hidden" border rounded="md">
  <AppShell layout="default">
    <AppShell.Header>
      <Header>
        <Header.Trigger />
        <Header.Brand>MyApp</Header.Brand>
        <Header.Nav>
          <Header.NavItem active>Dashboard</Header.NavItem>

Examples

Sidebar Layout

Sidebar runs full height with the header beside it.

import { ChartBar, Gear, House, MagnifyingGlass } from '@phosphor-icons/react';
import { AppShell } from '@/components/AppShell';
import { Box } from '@/components/Box';
import { Header } from '@/components/Header';
import { Icon } from '@/components/Icon';
import { Sidebar } from '@/components/Sidebar';

With Aside Panel

Adds a right rail for context, filters, or actions.

import { ChartBar, House } from '@phosphor-icons/react';
import { AppShell } from '@/components/AppShell';
import { Box } from '@/components/Box';
import { Header } from '@/components/Header';
import { Icon } from '@/components/Icon';
import { Sidebar } from '@/components/Sidebar';

Collapsible Icon Sidebar

Sidebar shrinks to icons on desktop via the footer toggle.

import { ChartBar, Gear, House } from '@phosphor-icons/react';
import { AppShell } from '@/components/AppShell';
import { Box } from '@/components/Box';
import { Header } from '@/components/Header';
import { Icon } from '@/components/Icon';
import { Sidebar } from '@/components/Sidebar';

Floating Main

Only the main slot floats — rounded, raised, on its own background.

import { ChartBar, Gear, House, MagnifyingGlass } from '@phosphor-icons/react';
import { AppShell } from '@/components/AppShell';
import { Box } from '@/components/Box';
import { Header } from '@/components/Header';
import { Icon } from '@/components/Icon';
import { Sidebar } from '@/components/Sidebar';

Floating Main & Aside

Two slots float independently; the sidebar stays flush.

import { ChartBar, Gear, House, MagnifyingGlass } from '@phosphor-icons/react';
import { AppShell } from '@/components/AppShell';
import { Box } from '@/components/Box';
import { Header } from '@/components/Header';
import { Icon } from '@/components/Icon';
import { Sidebar } from '@/components/Sidebar';

Floating Default Layout

Floating works under any layout, including header-on-top.

import { ChartBar, House } from '@phosphor-icons/react';
import { AppShell } from '@/components/AppShell';
import { Box } from '@/components/Box';
import { Header } from '@/components/Header';
import { Icon } from '@/components/Icon';
import { Sidebar } from '@/components/Sidebar';

Custom Backgrounds

Each slot takes its own bg, so regions read apart.

import { ChartBar, House } from '@phosphor-icons/react';
import { AppShell } from '@/components/AppShell';
import { Box } from '@/components/Box';
import { Header } from '@/components/Header';
import { Icon } from '@/components/Icon';
import { Sidebar } from '@/components/Sidebar';

API

Component props
Prop
Type
Default
Description
childrenRequirednodeNot setLayout content (use AppShell.Header, AppShell.Sidebar, AppShell.Main, AppShell.Aside)
layoutenumdefaultsidebarsidebar-floatingfloatingdefaultStructural layout for CSS grid areas
bgstringNot setBackground color override for the shell container (accepts any CSS color or token reference like "var(--fui-bg-secondary)")
styleobjectNot set—

Accessibility

  • Main content area has id="main-content" for skip links
  • Use Header.SkipLink for keyboard navigation
  • Sidebar drawer has proper focus trap on mobile
  • Keyboard navigation supported throughout

Guidance

Use when

  • Dashboards and internal tools
  • Apps with persistent sidebar navigation
  • Layouts needing header, sidebar, and main together
  • Navigation that must collapse to a drawer on mobile

Avoid when

  • Marketing and landing pages
  • Content-first sites with no app navigation
  • Single-screen tools with no chrome

Related

  • ThemeparentAppShell should be wrapped in ThemeProvider
  • HeaderchildHeader is placed inside AppShell.Header
  • SidebarchildSidebar content goes inside AppShell.Sidebar

Next steps