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:
-
The page list.
src/data/nav-manifest.jsonlists every page with its URL, title, icon and shell. The sidebar, the breadcrumbs, the command palette and the router all read this one file. -
The page files. Each page is a file in
src/pages/<group>/. Its name decides its URL. -
The page registry.
src/pages/pageRegistry.tsfinds every page file with Vite'simport.meta.globand 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:
{
"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:
{
"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:
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:
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.
{
"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
- Delete the page file, for example
src/pages/energy/Tariffs.tsx. - Delete its item from
nav-manifest.json. -
Search the project for the slug,
energy/tariffs, and remove any links to it. - Run
npm run checkto be sure nothing else uses it.
To remove a whole group, delete its folder in src/pages/ and its group in
the page list.
#Link to a page
Use React Router's Link or useNavigate, with
slugToPath from lib/manifest.ts:
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:
// 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');
#Sidebar badges
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:
{ "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 |