# Responsive app layout for React Native (Pro)

> AppShell, Page, Panel, DataTable, StatCard, QueryState, CommandPalette and AuthShell: the responsive layout behind Patine Pro's apps. One React Native codebase becomes a tab bar on phones, a navigation rail on tablets and a sidebar on desktop and the web, with a workspace switcher, favorites, counts and dots, a ⌘K command palette, G-then-letter shortcuts, a resizable sidebar and a usage card.

# App layout Pro

The pieces every [Pro app](./saas) is built from. They follow the width they're given, not the device: a tab bar on phones, a navigation rail from 640 points, and a sidebar with sections from 1024. Tables turn into cards on phones, actions move from labelled buttons into the top bar, and content stops at a readable width on big screens. Everything is built from free `patine-ui` components and React Native core.

```tsx
import { AppShell, Page, Panel, DataTable, StatCard, QueryState, useLayout } from '@patine-ui/pro';
```

## AppShell

The frame of an app: navigation, who's signed in, search, and the screen. Screens inside read their own width with `useLayout()`.

```tsx
<AppShell
  brand={{ name: 'Signal', mark: 'S' }}
  nav={[
    { key: 'home', label: 'Overview', icon: 'dashboard' },
    { key: 'invoices', label: 'Invoices', icon: 'fileText', badge: 3 },
    { key: 'team', label: 'Team', icon: 'users', section: 'Workspace' },
  ]}
  active={route}
  onNavigate={setRoute}
  user={{ name: 'Maya Lindqvist', email: 'maya@northpeak.io' }}
  onSearch={() => setPaletteOpen(true)}
  insets={useSafeAreaInsets()}
>
  {screen}
</AppShell>
```

| Width | Navigation |
| --- | --- |
| Under 640 | A bottom tab bar within thumb reach. Up to four tabs (or the keys in `tabs`), then **More** opens the rest in a sheet. With `phoneNav="drawer"`, a drawer instead: the Page's menu button opens it, and so does a swipe from the leading edge |
| 640 to 1023 | A navigation rail: icons with short labels down the side, as Material 3 and iPadOS do |
| 1024 and up | A sidebar with the app's name, search (⌘K), sections, groups that fold open, counts, pinned destinations and the signed-in user with their menu. It collapses to icons with tooltips (⌘B or Ctrl+B on the web) |

### Groups, pinned destinations and the account menu

Give an item `children` to fold destinations under it. A collapsed sidebar opens them in a menu; the tab bar and rail show
the group as one destination that opens its first child. `secondary` pins destinations such as Settings and Help to the
bottom, and `userActions` puts a menu on the signed-in user. `actions` adds a top bar on tablets and desktops with where you
are and your buttons, such as notifications.

```tsx
<AppShell
  brand={{ name: 'Signal' }}
  nav={[
    { key: 'home', label: 'Overview', icon: 'dashboard' },
    {
      key: 'planning',
      label: 'Planning',
      icon: 'layers',
      section: 'Product',
      children: [
        { key: 'roadmap', label: 'Roadmap', icon: 'calendarRange' },
        { key: 'board', label: 'Board', icon: 'kanban', badge: 3 },
      ],
    },
  ]}
  secondary={[{ key: 'settings', label: 'Settings', icon: 'settings' }]}
  userActions={[{ label: 'Profile' }, { label: 'Sign out', destructive: true, onPress: signOut }]}
  actions={<IconButton icon="bell" label="Notifications" />}
  phoneNav="drawer"
  active={route}
  onNavigate={setRoute}
>
  {screen}
</AppShell>
```

The tab bar takes each platform's design: 49-point bar with small labels on iOS, an 80-dp bar with a pill behind the active icon on Material.

| Prop | Type | Default |
| --- | --- | --- |
| `brand` | `{ name, mark?, color? }` | |
| `nav` | `NavItem[]`: `{ key, label, icon, badge?, section?, children? }` | |
| `active` | `string` | |
| `onNavigate` | `(key) => void` | |
| `tabs` | `string[]`, the keys on the phone tab bar | The first four |
| `user` | `{ name, email, avatar? }` | |
| `onSearch` | `() => void` | |
| `insets` | `{ top, bottom }` | None |
| `phoneNav` | `'tabs'` \| `'drawer'` | `'tabs'` |
| `secondary` | `NavItem[]`, pinned to the bottom of the sidebar and drawer, under More on phones | |
| `userActions` | `DropdownMenuAction[]`, a menu on the signed-in user | |
| `actions` | `ReactNode`, a top bar on tablets and desktops | |
| `collapsed`, `defaultCollapsed`, `onCollapsedChange` | `boolean`, the sidebar shows icons only | `false` |
| `commands`, `commandSource` | `Command[]` and `(query, signal) => Promise<Command[]>`: a [command palette](../components/command-palette) on ⌘K | |
| `workspaces`, `workspace`, `onWorkspaceChange`, `onCreateWorkspace` | `{ id, name, mark?, color?, plan?, members? }[]`, a switcher at the top of the sidebar | |
| `favorites` | `NavItem[]`, a Favorites section at the top | |
| `sidebarWidth`, `defaultSidebarWidth`, `onSidebarWidthChange` | `number`, dragged on the sidebar's edge (208 to 400) | `248` |
| `sidebarFooter` | `ReactNode`, above the user, such as a `UsageCard` | |

A `NavItem` is `{ key, label, icon, badge?, dot?, tag?, shortcut?, section?, children? }`: `badge` is a count, `dot` a new-thing dot without one, `tag` a small word ("New", "Beta"), and `shortcut` the letter that jumps there after G.

### A real product's shell

Everything together, as [Signal](./saas) uses it: a workspace switcher with plans and members, Favorites, counts, a dot and a New tag, a search with ⌘K that opens the command palette, notifications and help in the top bar, and a usage card with Upgrade above the user. Under 1024 points it becomes the rail, whose menu button opens the full sidebar over the screen.

```tsx live full
import { useState } from 'react';
import { View } from 'react-native';
import { Text } from 'patine-ui';
import { AppShell, Page, UsageCard, NotificationCenter } from '@patine-ui/pro';

const NAV = [
  { key: 'inbox', label: 'Inbox', icon: 'inbox', badge: 4, shortcut: 'i' },
  { key: 'issues', label: 'My issues', icon: 'circleDot', shortcut: 'm' },
  { key: 'cycles', label: 'Cycles', icon: 'refresh', section: 'Workspace', shortcut: 'c' },
  { key: 'projects', label: 'Projects', icon: 'layers', section: 'Workspace', dot: true, shortcut: 'p' },
  { key: 'insights', label: 'Insights', icon: 'barChart', section: 'Workspace', tag: 'New' },
];

const WORKSPACES = [
  { id: 'northwind', name: 'Northwind', mark: 'N', color: '#18181B', plan: 'Pro', members: 24 },
  { id: 'acme', name: 'Acme Labs', mark: 'A', color: '#6D5DFC', plan: 'Business', members: 86 },
];

export default function Example() {
  const [route, setRoute] = useState('inbox');
  const [workspace, setWorkspace] = useState('northwind');
  const label = [...NAV, { key: 'roadmap', label: 'Q4 roadmap' }].find((n) => n.key === route)?.label;
  return (
    <View style={{ height: 620, width: '100%' }}>
      <AppShell
        brand={{ name: 'Northwind' }}
        workspaces={WORKSPACES}
        workspace={workspace}
        onWorkspaceChange={setWorkspace}
        onCreateWorkspace={() => {}}
        favorites={[{ key: 'roadmap', label: 'Q4 roadmap', icon: 'star' }]}
        nav={NAV}
        secondary={[{ key: 'settings', label: 'Settings', icon: 'settings', shortcut: 's' }]}
        active={route}
        onNavigate={setRoute}
        user={{ name: 'Omer Katz', email: 'omer@northwind.dev' }}
        userActions={[{ label: 'Profile' }, { label: 'Sign out', destructive: true }]}
        commands={[
          { id: 'new', label: 'New issue', group: 'Actions', icon: 'plus', shortcut: ['C'] },
          { id: 'invite', label: 'Invite teammates', group: 'Actions', icon: 'userPlus' },
        ]}
        actions={<NotificationCenter notifications={[{ id: '1', title: 'Maya assigned you NW-482', createdAt: Date.now() - 300000, actor: { name: 'Maya Lindqvist' } }]} />}
        sidebarFooter={<UsageCard title="Issues this month" value={812} max={1000} description="Resets Dec 1" onAction={() => {}} />}
      >
        <Page title={label}>
          <Text color="textSecondary">Press ⌘K, or G then C to jump to Cycles. On a wide screen, drag the sidebar’s edge to resize it.</Text>
        </Page>
      </AppShell>
    </View>
  );
}
```

### Search and the command palette

Give `commands` and the shell opens a [command palette](../components/command-palette) with ⌘K or Ctrl+K and from every search button: in the sidebar, the rail, the top bar (where the sidebar's isn't showing) and More on phones. Every destination comes first under **Navigation**, with its section and its G shortcut, then your commands. `commandSource` adds results from your server as you type. Without `commands`, `onSearch` is yours to handle.

### Keyboard

On the web, **G then a letter** jumps to the destination with that `shortcut`, as in Linear and GitHub (outside text fields, within a second). ⌘B or Ctrl+B folds the sidebar to icons, whose tooltips show each shortcut. The palette lists them all.

### Workspaces, favorites and the usage card

`workspaces` puts a switcher at the top of the sidebar in place of the brand: the workspace's tile, name and plan, opening the list with plans and member counts, a check on the current one and **Create workspace** (a sheet on phones). `favorites` pins starred destinations in their own section at the top. `sidebarFooter` sits above the user; `UsageCard` is made for it: a meter that turns amber past 80% and red at the limit, a line under it, **Upgrade**, and an optional close button. On phones the footer moves into the More sheet.

### Resizing the sidebar

On the web the sidebar's trailing edge is a handle: drag it between 208 and 400 points (it follows the pointer without easing), or well past the least to fold it to icons. A keyboard can move it too: Tab to the handle, then ← → (Home and End for the least and most). Keep the width with `sidebarWidth` and `onSidebarWidthChange`, which reports it when a drag ends. It mirrors in right-to-left layouts.

### Tablets

From 640 to 1023 points the rail shows the workspace's tile, search, and a menu button that opens the full sidebar over the screen, with favorites, sections, counts and the usage card.

## Page

A screen's frame. On phones: the platform's top bar (a large title on iOS when there's no back button), actions as icon buttons, and an optional footer pinned above the tab bar. Wider: a page title with labelled actions, roomier padding, and content capped at `maxWidth`.

```tsx
<Page
  title="Invoices"
  subtitle="Bill customers and get paid faster"
  onBack={navigation.goBack}
  actions={[{ label: 'New invoice', icon: 'plus', onPress: create, primary: true }]}
  footer={<Button onPress={send}>Send invoice</Button>}
>
  {content}
</Page>
```

| Prop | Type | Default |
| --- | --- | --- |
| `title`, `subtitle` | `string` | |
| `onBack` | `() => void` | |
| `actions` | `{ label, icon, onPress, primary?, disabled? }[]` | `[]` |
| `footer` | `ReactNode`, pinned on phones, at the end of the content wider | |
| `scroll` | `boolean`, off for screens that fill the space, such as a chat or a board | `true` |
| `maxWidth` | `number` | `1200` |

## Data on screen

| Export | What it does |
| --- | --- |
| `Panel` | A titled card for one part of a screen, with an optional link (`action`) or control (`headerRight`). `flush` lets tables reach its edges |
| `StatCard` | A key number with its change in words, an arrow and color, and an optional sparkline. `good="down"` for churn and costs |
| `DataTable` | Sortable column headers, checkboxes for bulk actions and row presses on wide screens; on phones each row becomes a card you draw with `renderCard` |
| `useTable(rows, { id, columns, search?, initialSort? })` | The table's search, sort and selection: spread into `DataTable` |
| `QueryState` | Shows the content, a loading skeleton, a calm error with **Try again**, or a helpful empty state with a way out |
| `StatusBadge` | A status as a colored badge and a word: `paid`, `overdue`, `pending`… |
| `Grid` | Children in rows of equal columns; pick the count with `fitColumns(width, minWidth, gap, max)` |
| `Num` | Text with tabular figures, so amounts line up |

```tsx
const table = useTable(invoices, { id: (i) => i.id, columns, search: (i, q) => matches(q, i.number) });

<Panel title="Invoices" flush>
  <QueryState status={status} onRetry={refetch} empty={table.visible.length === 0} emptyTitle="Send your first invoice" inset>
    <DataTable
      columns={columns}
      rows={table.visible}
      rowKey={(i) => i.id}
      accessibilityLabel="Invoices"
      sort={table.sort}
      onSort={table.onSort}
      onRowPress={(i) => open(i.id)}
      renderCard={(i) => <InvoiceCard invoice={i} />}
    />
  </QueryState>
</Panel>
```

## CommandPalette

Search and jump anywhere: fuzzy search with the matched letters bold, Recent first, pages for nested commands, shortcuts, and results from your server. See [Command palette](../components/command-palette) for all of it; `AppShell` wires it in with `commands`.

```tsx
<CommandPalette
  open={open}
  onClose={() => setOpen(false)}
  commands={[
    { id: 'invoices', label: 'Invoices', group: 'Go to', icon: 'fileText', onSelect: () => go('invoices') },
    { id: 'new', label: 'New invoice', group: 'Actions', icon: 'plus', hint: 'N', onSelect: create },
  ]}
/>
```

## AuthShell

The frame for sign-in and other screens outside the app: the form alone on phones, keyboard-aware; beside a brand panel with a headline and a customer quote from 1024 points. Set `scroll={false}` for a screen that scrolls itself.

```tsx
<AuthShell brand={{ name: 'Orbit' }} headline="Plan less. Do more." quote={{ text: '…', author: 'Joana Reis', role: 'COO' }}>
  <SignUpScreen onSubmit={signUp} onSignIn={goToSignIn} />
</AuthShell>
```

## useLayout

What every screen asks to choose its layout. Inside `AppShell` it's the space next to the navigation, not the window.

```tsx
const { width, breakpoint, wide, desktop, insets } = useLayout();
```

| Field | Meaning |
| --- | --- |
| `breakpoint` | `'compact'` (under 640), `'medium'` (640+), `'expanded'` (1024+) or `'wide'` (1360+) |
| `wide` | Wider than a phone: two columns, labelled actions |
| `desktop` | A sidebar fits: tables, side panels |

## Helpers

| Export | What it does |
| --- | --- |
| `useStack({ route, param? })` | A small in-memory navigation stack: `push`, `back`, `reset`. Apps with React Navigation or Expo Router wire screens to theirs instead |
| `formatMoney(cents, currency?, locale?, compact?)` | `formatMoney(129900)` is `$1,299.00`; `compact` rounds for headline figures |
| `formatAgo`, `formatDay`, `formatDelta`, `formatCompact`, `dayHeading` | "3h ago", "Nov 12", "+4.3%", "12.4K", "Yesterday" |
| `matches(query, ...fields)` | Search that ignores case and accents |
| `demoStatus(state)`, `demoData(state, rows)` | Show a screen loading, empty or failed, for previews and tests |
| `UsageCard`, `WorkspaceSwitcher` | The sidebar's usage meter with Upgrade, and its workspace switcher on its own |
| `navCommands(nav, onNavigate)`, `nextGo`, `settleSidebarWidth` | The palette's Navigation group, the G-then-letter step, and where a dragged sidebar settles |
| `Icon`, `IconButton`, `Pressy` | Line icons by name, a 44-point icon button with a label, and a pressable with hover, press and focus states |
