Page patterns
Most pages in Atmosphere are built on a small set of page layouts. Use the same layouts for your own pages, and you get search, tables, tabs, wizards and app frames with very little code.
#Overview
All page layouts are in src/components/patterns/, except
PageHead, which is in src/components/shell/.
| Layout | Use it for | Used by |
|---|---|---|
PageHead + .am-grid |
Dashboards and any free layout | 6 dashboards, 5 pages |
ListPage |
A searchable, sortable, paged table | 22 list pages |
DetailPage |
One record, with tabs and a side column | 5 detail pages |
FormPage |
A form, or a wizard with steps | 5 forms |
AppFrame |
A full-screen app with its own toolbar | 8 apps |
AuthPage |
A sign-in card in the center of the screen | 7 sign-in pages |
ErrorPage |
An error code, a message and a way back | 6 error pages |
The quickest way to start a new page is to copy a page of the same kind and change it. The route list shows the kind of every page.
#PageHead
The header at the top of a page: the breadcrumb, a small line above the title (the eyebrow), the title, a subtitle, and buttons on the right.
import { IconPlus } from '@tabler/icons-react';
import { PageHead } from '@/components/shell/PageHead';
import { Button } from '@/components/ui/Button';
<PageHead
title="Meters"
eyebrow="Energy"
subtitle="Eight meters across three utilities."
actions={
<Button variant="accent" icon={IconPlus}>
Add meter
</Button>
}
/>;
| Prop | Type | What it does |
|---|---|---|
title |
string |
The page title. Required. |
eyebrow |
ReactNode |
The small uppercase line above the title. |
subtitle |
string |
One line under the title. |
actions |
ReactNode |
Buttons, tabs or chips on the right. |
crumbs |
boolean |
Set to false to hide the breadcrumb. The breadcrumb comes from
the page list, so you never write it.
|
#The card grid
Dashboards use a 12-column grid. Put Card components inside
.am-grid and give each card a span from 3 to 12.
import { Stagger } from '@/components/motion/Stagger';
import { CountUp } from '@/components/motion/CountUp';
import { Card, CardHead } from '@/components/ui/Card';
<div className="am-grid">
<Stagger>
<Card span={3}>
<div className="am-kpi__label">Energy today</div>
<div className="am-kpi__value">
<CountUp value={1284} />
</div>
</Card>
<Card span={9}>
<CardHead title="Demand" aside={<a href="#">Details</a>} />
{/* a chart */}
</Card>
</Stagger>
</div>;
-
Staggermakes the cards settle in one after another. See Motion. - At 1180px and below, spans of 3, 4, 5, 7, 8 and 9 become half width. At 760px and below, every card is full width.
-
The gap between cards is the
--am-guttertoken. It is smaller in compact density.
Other layout classes you can use anywhere:
| Class | What it does |
|---|---|
.am-stack |
A vertical column with a standard gap. .am-stack--tight and
.am-stack--loose change the gap.
|
.am-row |
A horizontal row that wraps. .am-row--tight,
.am-row--between and .am-row--end change the gap and
alignment.
|
.am-section |
A vertical group with a larger gap, for page sections. |
.am-muted, .am-quiet |
Secondary and muted text color. |
.am-good-text, .am-warn-text,
.am-bad-text, .am-info-text,
.am-accent-text
|
Colored text that passes contrast checks. |
.am-kpi__label, .am-kpi__value,
.am-kpi__sub, .am-kpi__foot
|
The parts of a number card on a dashboard. |
.am-sr |
Hides text visually but keeps it for screen readers. |
You can also use Tailwind utilities for layout inside a page. See Theming.
#ListPage
A full list page: search, a filter strip, a sortable table, row selection with bulk actions, and pagination. Your page only gives it the data and the columns.
import { IconDownload } from '@tabler/icons-react';
import { ListPage } from '@/components/patterns/ListPage';
import { Chip, Status } from '@/components/ui/Badge';
import { type Column } from '@/components/ui/Table';
interface Meter {
id: string;
name: string;
kind: string;
status: 'online' | 'offline';
}
const columns: Column<Meter>[] = [
{ key: 'id', header: 'ID', cell: (m) => <span className="am-table__id">{m.id}</span>, sortBy: (m) => m.id },
{ key: 'name', header: 'Meter', cell: (m) => <b>{m.name}</b>, sortBy: (m) => m.name },
{ key: 'kind', header: 'Kind', cell: (m) => <Chip small>{m.kind}</Chip> },
{
key: 'status',
header: 'Status',
cell: (m) => <Status tone={m.status === 'online' ? 'good' : 'bad'}>{m.status}</Status>,
},
];
export default function Meters(): React.JSX.Element {
return (
<ListPage
title="Meters"
eyebrow="Energy"
rows={meters}
columns={columns}
rowKey={(m) => m.id}
searchIn={(m) => `${m.id} ${m.name} ${m.kind}`}
filters={[
{ value: 'all', label: 'All' },
{ value: 'offline', label: 'Offline', match: (m) => m.status === 'offline' },
]}
bulk={[{ label: 'Export', icon: IconDownload, onClick: (ids) => console.log(ids) }]}
perPage={10}
/>
);
}
| Prop | Type | What it does |
|---|---|---|
title |
string |
The page title. Required. |
rows |
Row[] |
The data. Required. |
columns |
Column<Row>[] |
The table columns. Required. See Table. |
rowKey |
(row) => string |
A unique ID for each row. Required. |
searchIn |
(row) => string |
The text the search box looks in. Leave it out to hide the search box. |
searchPlaceholder |
string |
Placeholder for the search box. Default "Search".
|
filters |
ListFilter<Row>[] |
The filter strip. Each filter has value, label and
an optional match(row). The first one usually has no
match, so it shows everything.
|
summary |
ReactNode |
Chips beside the filter strip, such as a count. |
bulk |
BulkAction[] |
Turns on row checkboxes. Each action has label,
onClick(selectedIds) and optional icon and
danger.
|
perPage |
number |
Rows per page. Default 8. |
onRowClick |
(row) => void |
Runs when a row is clicked, for example to open the detail page. |
eyebrow, subtitle, actions |
Passed to PageHead. |
|
children |
ReactNode |
Anything above the table, such as number cards or an alert. |
emptyTitle, emptyDescription |
string |
The message when no row matches. |
When a filter makes the list shorter, the current page number is kept if it still exists. The reader is not sent back to page one.
#DetailPage
One record: a header with chips, tabbed sections, and a side column that stays in place while the main column scrolls.
import { IconActivity, IconSettings } from '@tabler/icons-react';
import { DetailPage, Facts } from '@/components/patterns/DetailPage';
import { Chip } from '@/components/ui/Badge';
<DetailPage
title="Rooftop HVAC"
eyebrow="Devices"
meta={<Chip led="good">Running</Chip>}
sections={[
{ value: 'live', label: 'Live', icon: IconActivity, content: <LiveReadings /> },
{ value: 'settings', label: 'Settings', icon: IconSettings, content: <DeviceSettings /> },
]}
side={
<Facts
title="Details"
items={[
{ label: 'Gateway', value: 'GW-02' },
{ label: 'Firmware', value: '4.2.1' },
]}
/>
}
/>;
| Prop | Type | What it does |
|---|---|---|
title |
string |
Required. |
sections |
DetailSection[] |
The tabs. Each has value, label,
content and an optional icon. With one section, the
tab strip is hidden. Required.
|
meta |
ReactNode |
Chips and status under the title. |
side |
ReactNode |
The right column. Facts is made for it: a list of labels and
values.
|
eyebrow, subtitle, actions |
Passed to PageHead. |
|
children |
ReactNode |
Anything full width above the two columns. |
#FormPage
A form with one step, or a wizard with several steps and an optional review step. It shows the step rail, the error message, and a sticky bar with Back, Continue and Save.
import { useState } from 'react';
import { FormPage } from '@/components/patterns/FormPage';
import { Card } from '@/components/ui/Card';
import { Field, Input } from '@/components/ui/Input';
export default function AddDevice(): React.JSX.Element {
const [name, setName] = useState('');
return (
<FormPage
title="Add device"
steps={[
{
value: 'name',
label: 'Name',
content: (
<Card>
<Field label="Device name" htmlFor="name" required>
<Input id="name" value={name} onChange={(e) => setName(e.target.value)} />
</Field>
</Card>
),
validate: () => (name.trim() === '' ? 'Give the device a name.' : null),
},
{ value: 'place', label: 'Place', content: <PlaceStep /> },
]}
review={<p>{name}</p>}
submitLabel="Pair device"
submitMessage="Device paired."
/>
);
}
| Prop | Type | What it does |
|---|---|---|
title |
string |
Required. |
steps |
FormStep[] |
Each step has value, label, content and
an optional validate(). validate returns an error
message to stop the step, or null to continue. Required.
|
review |
ReactNode |
A last step that shows a summary before the final press. |
submitLabel |
string |
The text on the last button. Default "Save changes".
|
submitMessage |
string |
The toast message after a successful submit. Default
"Saved.".
|
side |
ReactNode |
A side column next to the form. |
eyebrow, subtitle, actions,
children
|
As in the other layouts. |
#Send the form to your server
In the template, a valid form only shows a toast message. Nothing is sent. To send the
data, add an onSubmit prop to FormPage. Open
src/components/patterns/FormPage.tsx and make three small changes:
// 1. Add the prop to FormPageProps
onSubmit?: () => void | Promise<void>;
// 2. Read it in the function arguments
export function FormPage({ /* ...the existing props */ onSubmit }: FormPageProps) {
// 3. Call it in submit(), before the toast
const submit = async (event: FormEvent): Promise<void> => {
event.preventDefault();
const problem = step?.validate?.() ?? null;
if (problem) {
setError(problem);
return;
}
setError(null);
try {
await onSubmit?.();
toast.push({ message: submitMessage, tone: 'good' });
} catch {
setError('We could not save this. Please try again.');
}
};
Then pass your own function from the page:
onSubmit={() => api.post('/devices', { name })}.
#AppFrame
A full-screen app: a title bar with your own toolbar, an optional rail on the left,
one scrolling body, and an optional column on the right. Use it inside a page whose
shell is FocusShell in the page list.
import { AppFrame, RailItem } from '@/components/patterns/AppFrame';
<AppFrame
title="Notes"
toolbar={<Button variant="accent" icon={IconPlus}>New note</Button>}
rail={
<>
<RailItem label="Everything" active onClick={() => setFolder(null)} />
<RailItem label="Plant room" onClick={() => setFolder('plant')} />
</>
}
aside={<NoteDetails />}
>
<NoteList />
</AppFrame>;
| Prop | Type | What it does |
|---|---|---|
title |
string |
Required. |
children |
ReactNode |
The main body. Required. |
toolbar |
ReactNode |
Chips and buttons in the app's own bar. There is no
PageHead in an app.
|
rail |
ReactNode |
The left column, usually RailItems. |
aside |
ReactNode |
The right column. |
scroll |
boolean |
Set to false when the body manages its own scrolling. |
RailItem takes label, and optional icon,
badge, active and onClick. The rail and the
right column are hidden below 1100px wide.
#AuthPage
The sign-in card: the logo, a title, one sentence, your form, and a line under the
card. Use it in a page whose shell is Bare.
import { Link } from 'react-router-dom';
import { AuthPage } from '@/components/patterns/AuthPage';
import { slugToPath } from '@/lib/manifest';
<AuthPage
title="Reset your password"
description="Give us the address you sign in with and we will send a link."
foot={<Link to={slugToPath('auth/sign-in')}>Back to sign in</Link>}
>
<form className="am-stack">{/* fields and a button */}</form>
</AuthPage>;
| Prop | Type | What it does |
|---|---|---|
title |
string |
Required. |
description |
string |
One sentence under the title. Required. |
children |
ReactNode |
The form. Required. |
foot |
ReactNode |
The line under the card. |
wide |
boolean |
A wider card, for two columns of fields. |
header |
ReactNode |
Content above the title, such as an avatar. |
The sign-in pages check their fields and then go to the overview. Connect the
submit function in each page to your login service.
#ErrorPage
import { IconError404 } from '@tabler/icons-react';
import { ErrorPage } from '@/components/patterns/ErrorPage';
<ErrorPage
code="404"
title="That page is not here"
description="The link may be old, or the record was removed."
icon={IconError404}
/>;
| Prop | Type | What it does |
|---|---|---|
code |
string |
The large code, or a word for pages without one. Required. |
title, description |
string |
Required. |
icon |
Tabler icon | Required. Pass the component, for example IconError404. |
children |
ReactNode |
Anything under the buttons. |
home |
boolean |
Set to false to hide the "Back to overview" button.
|