AppShell

Introduction

AppShell is a collection of mobile-first layout components for React. Build native-feeling mobile web apps with scroll-aware headers, footers, sidebars, and safe areas.

Features

  • Header - 6 scroll behaviors including fixed, reveal, and sticky variants
  • Footer - Tab bar, floating action, and mini bar variants with auto-hide
  • Sidebar - Slide-out drawer with backdrop and keyboard dismiss
  • SafeArea - Automatic safe area inset handling for notched devices
  • ScrollNav - Horizontal scrollable navigation pills
  • Context - Shared state for header/footer visibility and scroll direction

Installation

Install AppShell using your preferred package manager:

bash
1npm install appshell-react
2# or
3pnpm add appshell-react
4# or
5yarn add appshell-react

Basic Usage

Here is a simple example showing the core components working together:

app.tsx
1import { AppShell, Header, Content, Footer, FooterItem } from "appshell-react";
2import { Home, Search, Bell, User } from "lucide-react";
3 
4export default function App() {
5  return (
6    <AppShell safeArea>
7      <Header 
8        behavior="fixed" 
9        logo={<span className="font-bold">My App</span>}
10        title="Dashboard"
11        subtitle="Overview"
12      />
13      <Content className="p-4">
14        <h1 className="text-2xl font-bold">Welcome!</h1>
15        <p className="text-muted-foreground mt-2">
16          Start building your mobile-first app.
17        </p>
18      </Content>
19      <Footer variant="tab-bar">
20        <FooterItem icon={<Home />} label="Home" active />
21        <FooterItem icon={<Search />} label="Search" />
22        <FooterItem icon={<Bell />} label="Alerts" badge={3} />
23        <FooterItem icon={<User />} label="Profile" />
24      </Footer>
25    </AppShell>
26  );
27}

Animations (Optional)

AppShell works without any animation library. For smooth animations, you can optionally add Framer Motion:

bash
1npm install framer-motion

Then wrap your app with the MotionProvider:

app.tsx
1import { MotionProvider } from "appshell-react";
2import { framerMotionAdapter } from "appshell-react/motion-framer";
3 
4export default function App() {
5  return (
6    <MotionProvider adapter={framerMotionAdapter}>
7      <AppShell safeArea>
8        {/* Your app content */}
9      </AppShell>
10    </MotionProvider>
11  );
12}

Design Tokens

AppShell uses shadcn/ui design tokens out of the box. All components automatically adapt to your theme using CSS custom properties like --background, --foreground, --primary, etc.

Dark mode works automatically when you toggle the .dark class on your root element.

ComponentsView Examples