App layout Pro
The pieces every Pro app 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.
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().
<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}
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.
<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 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 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.
<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: '[email protected]' }} 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 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.
<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 |
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 for all of it; AppShell wires it in with commands.
<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.
<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.
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 |