Skip to content
DocsBuild
Build

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.

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.

TSX
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.

TSX
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>;
  • Stagger makes 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-gutter token. 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.

TSX
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.

TSX
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.

TSX
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:

TSX
// 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.

TSX
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.

TSX
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

TSX
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.