Skip to content
DocsBuild
Build

Pages and routing

Every page is one file, and one list decides where it appears. This page explains how a URL becomes a page, and how to add, rename or remove one.

#How it works

Three parts work together:

  1. The page list. src/data/nav-manifest.json lists every page with its URL, title, icon and shell. The sidebar, the breadcrumbs, the command palette and the router all read this one file.
  2. The page files. Each page is a file in src/pages/<group>/. Its name decides its URL.
  3. The page registry. src/pages/pageRegistry.ts finds every page file with Vite's import.meta.glob and loads each one only when you visit it.

There is no list of <Route> elements to keep up to date. App.tsx has one route that catches every path. For each path it does this:

The page list has the URL A page file exists Result
Yes Yes The page, inside its shell
Yes No A "not built yet" placeholder, inside its shell
No Any The 404 page

#From file name to URL

The folder is the first part of the URL. The file name, changed from PascalCase to kebab-case, is the second part.

File URL
src/pages/home/Overview.tsx /home/overview
src/pages/energy/MeterDetail.tsx /energy/meter-detail
src/pages/access/VisitorPass.tsx /access/visitor-pass

A file name cannot start with a number, so the error pages are named Error404.tsx and so on. SLUG_OVERRIDES, at the top of pageRegistry.ts, maps those files to their URLs. Use the same map if one of your pages needs a URL that its file name cannot make.

The home URL / opens the page named in "default" at the top of nav-manifest.json. It is home/overview.

#The page list

nav-manifest.json has three sections:

Section Where its groups appear
primary The keys in the left sidebar: Home, Energy, Climate, Devices, Work orders, Access, Residents and Design kit.
avatar The menu behind the avatar key: Workspace and Account.
foundation Sign-in and error pages. They are in the command palette, but not in the sidebar.

Each section has groups, and each group has items. One item looks like this:

JSON
{
  "slug": "energy/meters",
  "title": "Meters",
  "kind": "L",
  "shell": "KeypadShell",
  "icon": "IconGauge",
  "keywords": ["submeters", "readings"]
}
Field Required What it does
slug Yes The URL without the first /. It must match the page file.
title Yes Shown in the sidebar menu, the breadcrumb and the command palette.
kind Yes A one-letter label: D dashboard, L list, V detail, F form, A app, P page, K design kit, U sign-in, E error. It is used for labels only.
shell Yes KeypadShell, FocusShell or Bare. See Shells.
icon Yes The name of a Tabler icon, for example IconGauge. See Icons in the page list.
keywords Yes Extra words the command palette searches. Use [] for none.
badge No On a group, the name of a number in src/data/demo/counters.json. The sidebar key shows that number.

#Shells

A shell is the frame around a page. The page list chooses it for each page.

Shell What it shows Used by
KeypadShell The sidebar keypad. The page draws its own header with PageHead. Most pages
FocusShell The same keypad. The page fills all the space and draws its own toolbar. Apps: inbox, chat, calendar, notes, the board, schedules
Bare No sidebar. The page sits in the center of the screen. Sign-in and error pages

All three shells live in src/components/shell/Shells.tsx. The two keypad shells also hold the command palette, the Appearance drawer and the toast messages.

On screens 900px wide or smaller, the keypad moves to a dock along the bottom of the screen.

#Add a page

Here we add a page called Water to the Energy group.

1. Add it to the page list. In src/data/nav-manifest.json, find the energy group and add an item:

JSON
{
  "slug": "energy/water",
  "title": "Water",
  "kind": "D",
  "shell": "KeypadShell",
  "icon": "IconDroplet",
  "keywords": ["usage", "leaks"]
}

2. Create the file src/pages/energy/Water.tsx with a default export:

TSX
import { PageHead } from '@/components/shell/PageHead';
import { Card, CardHead } from '@/components/ui/Card';
import { Stagger } from '@/components/motion/Stagger';

export default function Water(): React.JSX.Element {
  return (
    <>
      <PageHead title="Water" eyebrow="Energy" />
      <div className="am-grid">
        <Stagger>
          <Card span={6}>
            <CardHead title="Today" />
            <p>Your content here.</p>
          </Card>
          <Card span={6}>
            <CardHead title="This month" />
            <p>Your content here.</p>
          </Card>
        </Stagger>
      </div>
    </>
  );
}

3. Open http://localhost:5192/energy/water. That is all. The page is in the sidebar menu, the breadcrumb and the command palette.

#Icons in the page list

The page list names icons as text, such as "IconGauge". src/components/ui/navIcons.ts turns each name into the icon component. It imports only the icons the page list uses, so your build stays small.

To use a new icon, add it to the import list and to the ICONS object in that file:

TSX
import {
  // ...the icons already there
  IconDroplet,
} from '@tabler/icons-react';

const ICONS: Record<string, TablerIcon> = {
  // ...the icons already there
  IconDroplet,
};

Find icon names at tabler.io/icons. Add Icon in front of the name and write it in PascalCase: droplet becomes IconDroplet.

#Add a group

A new group in the primary section becomes a new key in the sidebar.

JSON
{
  "id": "parking",
  "title": "Parking",
  "icon": "IconParking",
  "items": [
    {
      "slug": "parking/spaces",
      "title": "Spaces",
      "kind": "L",
      "shell": "KeypadShell",
      "icon": "IconParking",
      "keywords": ["bays", "permits"]
    }
  ]
}

Then create src/pages/parking/Spaces.tsx. The group's key opens a menu with its pages, and pressing the key opens the first page.

Put the group in the avatar section instead if it should appear in the avatar menu.

#Rename a page

To change only the title, edit title in the page list.

To change the URL, change slug in the page list and rename the file so the two still match. Then search the project for the old slug. Pages link to each other with slugToPath('energy/meters'), so a text search finds every link.

#Remove a page

  1. Delete the page file, for example src/pages/energy/Tariffs.tsx.
  2. Delete its item from nav-manifest.json.
  3. Search the project for the slug, energy/tariffs, and remove any links to it.
  4. Run npm run check to be sure nothing else uses it.

To remove a whole group, delete its folder in src/pages/ and its group in the page list.

Use React Router's Link or useNavigate, with slugToPath from lib/manifest.ts:

TSX
import { Link, useNavigate } from 'react-router-dom';
import { slugToPath } from '@/lib/manifest';

<Link to={slugToPath('devices/device-detail')}>Open the device</Link>;

const navigate = useNavigate();
void navigate(slugToPath('work/list'));

#Detail pages and record IDs

In the demo, each detail page (a device, a meter, a resident) always shows one example record. The URL has no record ID.

When you connect your data, pass the ID in the query string. This needs no change to the router:

TSX
// Link to /devices/device-detail?id=DEV-1041
<Link to={`${slugToPath('devices/device-detail')}?id=${device.id}`}>{device.name}</Link>;

// Read it on the detail page
import { useSearchParams } from 'react-router-dom';

const [params] = useSearchParams();
const id = params.get('id');

A group can show a number on its sidebar key, like the open work orders. Set "badge" on the group to a key in src/data/demo/counters.json:

JSON
{ "id": "work", "title": "Work orders", "icon": "IconTool", "badge": "openWorkOrders", "items": [] }

In your own app, replace the counters file with live numbers. src/components/shell/Keypad.tsx reads them.

#Every route

The full list of pages in the template.

#Home

URL Title Kind Shell
/home/overview Overview Dashboard Keypad
/home/building Building Dashboard Keypad
/home/floor-plan Floor plan Page Keypad
/home/wall Lobby display Dashboard Keypad

#Energy

URL Title Kind Shell
/energy/overview Energy Dashboard Keypad
/energy/meters Meters List Keypad
/energy/meter-detail Meter Detail Keypad
/energy/solar-storage Solar and storage Dashboard Keypad
/energy/tariffs Tariffs Page Keypad
/energy/reports Reports List Keypad

#Climate

URL Title Kind Shell
/climate/zones Zones List Keypad
/climate/zone-detail Zone Detail Keypad
/climate/schedules Schedules App Focus
/climate/scenes Scenes List Keypad
/climate/scene-editor Scene editor Form Keypad
/climate/air-quality Air quality Dashboard Keypad

#Devices

URL Title Kind Shell
/devices/list Devices List Keypad
/devices/device-detail Device Detail Keypad
/devices/gateways Gateways List Keypad
/devices/firmware Firmware List Keypad
/devices/alerts Device alerts List Keypad
/devices/add-device Add device Form Keypad

#Work orders

URL Title Kind Shell
/work/board Board App Focus
/work/list Work orders List Keypad
/work/work-order-detail Work order Detail Keypad
/work/preventive Preventive maintenance App Focus
/work/vendors Vendors List Keypad
/work/parts Parts List Keypad

#Access

URL Title Kind Shell
/access/feed Access feed List Keypad
/access/doors Doors and locks List Keypad
/access/credentials Credentials List Keypad
/access/visitors Visitors List Keypad
/access/visitor-pass Visitor pass Form Keypad
/access/cameras Cameras Page Keypad

#Residents

URL Title Kind Shell
/residents/directory Directory List Keypad
/residents/resident-detail Resident Detail Keypad
/residents/units Units List Keypad
/residents/leases Leases List Keypad
/residents/requests Requests List Keypad
/residents/announcements Announcements Form Keypad
/residents/amenities Amenities App Focus

#Design kit

URL Title Kind Shell
/ui/buttons Buttons and keycaps Design kit Keypad
/ui/inputs Inputs Design kit Keypad
/ui/selection Selection Design kit Keypad
/ui/dials Dials and sliders Design kit Keypad
/ui/status Status Design kit Keypad
/ui/navigation Navigation Design kit Keypad
/ui/feedback Feedback Design kit Keypad
/ui/surfaces Surfaces Design kit Keypad
/ui/typography Typography Design kit Keypad
/ui/charts Charts Design kit Keypad
/ui/tables Tables Design kit Keypad
/ui/icons Icons Design kit Keypad
/ui/motion Motion Design kit Keypad

#Workspace

URL Title Kind Shell
/workspace/inbox Inbox App Focus
/workspace/chat Chat App Focus
/workspace/calendar Calendar App Focus
/workspace/notes Notes App Focus
/workspace/team Team List Keypad
/workspace/audit-log Audit log List Keypad

#Account

URL Title Kind Shell
/account/profile Profile Page Keypad
/account/settings Settings Form Keypad
/account/integrations Integrations List Keypad
/account/billing Billing Page Keypad

#Authentication

URL Title Kind Shell
/auth/sign-in Sign in Sign-in Bare
/auth/sign-up Sign up Sign-in Bare
/auth/forgot-password Forgot password Sign-in Bare
/auth/reset-password Reset password Sign-in Bare
/auth/two-factor Two-factor code Sign-in Bare
/auth/lock-screen Lock screen Sign-in Bare
/auth/invite Accept invite Sign-in Bare

#Errors

URL Title Kind Shell
/error/401 401 Unauthorized Error Bare
/error/403 403 Forbidden Error Bare
/error/404 404 Not found Error Bare
/error/500 500 Server error Error Bare
/error/503 503 Unavailable Error Bare
/error/maintenance Maintenance Error Bare