Installation

Get started with AppShell in your React project.

Install the package

Install AppShell using your preferred package manager:

npm

1npm install appshell-react

pnpm

1pnpm add appshell-react

yarn

1yarn add appshell-react

Basic Setup

Import and use the components in your app:

app.tsx

1import { AppShell, Header, Content, Footer, FooterItem } from "appshell-react";
2import { Home, Search, 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      />
11      <Content className="p-4">
12        <h1>Hello World</h1>
13      </Content>
14      <Footer variant="tab-bar">
15        <FooterItem icon={<Home />} label="Home" active />
16        <FooterItem icon={<Search />} label="Search" />
17        <FooterItem icon={<User />} label="Profile" />
18      </Footer>
19    </AppShell>
20  );
21}

Add Animations (Optional)

AppShell works without any animation library. For smooth, spring-based animations, optionally add Framer Motion:

bash

1npm install framer-motion

Then wrap your app with MotionProvider:

app.tsx

1import { AppShell, 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 with smooth animations */}
9      </AppShell>
10    </MotionProvider>
11  );
12}

Tailwind CSS Setup

AppShell uses CSS custom properties for theming, compatible with shadcn/ui tokens. Make sure your CSS includes these variables:

globals.css

1// tailwind.config.js (v3) or globals.css (v4)
2// AppShell uses these CSS variables for theming:
3 
4:root {
5  --background: 0 0% 100%;
6  --foreground: 0 0% 3.9%;
7  --primary: 0 0% 9%;
8  --primary-foreground: 0 0% 98%;
9  --muted: 0 0% 96.1%;
10  --muted-foreground: 0 0% 45.1%;
11  --accent: 0 0% 96.1%;
12  --accent-foreground: 0 0% 9%;
13  --border: 0 0% 89.8%;
14}
15 
16.dark {
17  --background: 0 0% 3.9%;
18  --foreground: 0 0% 98%;
19  /* ... dark mode values */
20}

Requirements

React 18 or higher
Tailwind CSS 4.x (or 3.x with proper config)
Framer Motion 10+ (optional, for animations)

TypeScript Support

AppShell is written in TypeScript and includes full type definitions. No additional @types packages are needed.

Next: Theming