Skip to main content

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}
user={{ name: 'Maya Lindqvist', email: '[email protected]' }}
onSearch={() => setPaletteOpen(true)}
insets={useSafeAreaInsets()}
>
{screen}
</AppShell>
WidthNavigation
Under 640A 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 1023A navigation rail: icons with short labels down the side, as Material 3 and iPadOS do
1024 and upA 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.

PropTypeDefault
brand{ name, mark?, color? }
navNavItem[]: { key, label, icon, badge?, section?, children? }
activestring
onNavigate(key) => void
tabsstring[], the keys on the phone tab barThe first four
user{ name, email, avatar? }
onSearch() => void
insets{ top, bottom }None
phoneNav'tabs' | 'drawer''tabs'
secondaryNavItem[], pinned to the bottom of the sidebar and drawer, under More on phones
userActionsDropdownMenuAction[], a menu on the signed-in user
actionsReactNode, a top bar on tablets and desktops
collapsed, defaultCollapsed, onCollapsedChangeboolean, the sidebar shows icons onlyfalse
commands, commandSourceCommand[] 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
favoritesNavItem[], a Favorites section at the top
sidebarWidth, defaultSidebarWidth, onSidebarWidthChangenumber, dragged on the sidebar's edge (208 to 400)248
sidebarFooterReactNode, 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.

Loading…
<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>
PropTypeDefault
title, subtitlestring
onBack() => void
actions{ label, icon, onPress, primary?, disabled? }[][]
footerReactNode, pinned on phones, at the end of the content wider
scrollboolean, off for screens that fill the space, such as a chat or a boardtrue
maxWidthnumber1200

Data on screen​

ExportWhat it does
PanelA titled card for one part of a screen, with an optional link (action) or control (headerRight). flush lets tables reach its edges
StatCardA key number with its change in words, an arrow and color, and an optional sparkline. good="down" for churn and costs
DataTableSortable 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
QueryStateShows the content, a loading skeleton, a calm error with Try again, or a helpful empty state with a way out
StatusBadgeA status as a colored badge and a word: paid, overdue, pending…
GridChildren in rows of equal columns; pick the count with fitColumns(width, minWidth, gap, max)
NumText 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();
FieldMeaning
breakpoint'compact' (under 640), 'medium' (640+), 'expanded' (1024+) or 'wide' (1360+)
wideWider than a phone: two columns, labelled actions
desktopA sidebar fits: tables, side panels

Helpers​

ExportWhat 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, WorkspaceSwitcherThe sidebar's usage meter with Upgrade, and its workspace switcher on its own
navCommands(nav, onNavigate), nextGo, settleSidebarWidthThe palette's Navigation group, the G-then-letter step, and where a dragged sidebar settles
Icon, IconButton, PressyLine icons by name, a 44-point icon button with a label, and a pressable with hover, press and focus states