Common questions
On this page
What is the PH App Kit for?
Apps, dashboards, reports and tools that run inside Performance Hub, or alongside it. It makes them look and behave like Performance Hub with little work. Websites, landing pages and design-led pages don't need it.
Do I have to use React?
No. Most of the kit is plain HTML classes and window.phApp, so any page works: static HTML,
server-rendered templates, or any framework. React apps can use ph-app-kit-react for ready-made
components. See React.
Can I use other libraries?
Yes. Use the kit's components and modules first, since they already match. For anything they don't cover, use any library: prefer one that can be themed, style it with kit tokens so it matches in light and dark, and avoid a second full CSS framework. See Guidelines.
Why does my page look wrong in dark mode?
Something is using a hard-coded colour such as #fff or black. Use tokens instead:
rgb(var(--ph-surface)) for backgrounds, rgb(var(--ph-primary)) for text. Charts drawn with your
own Chart.js code need their colours read from the tokens and updated in phApp.onThemeChange().
See Theming.
Why is my chart colour black?
You've passed a token such as rgb(var(--ph-red-3)) to Chart.js directly (window.Chart). It draws
on a canvas, which can't read CSS variables. The kit's charts resolve tokens for you; with
window.Chart, read the token's value yourself, as Charts shows.
Why do my API calls or assets 404 inside Performance Hub?
An app doesn't always open at the root of its address, and URLs starting with / point at the root of the whole site. Use relative
URLs (api/items), phApp.url(), or phApp.fetchJSON(). In Vite, set base: './'. See
Performance Hub integration.
Why doesn't Ctrl/Cmd+K work in my app?
It does, but it opens Performance Hub's search. Ctrl/Cmd+K, Ctrl/Cmd+J, Ctrl/Cmd+I and Alt+Ctrl/Cmd+L belong to Performance Hub, and the kit passes them up. Pick other shortcuts for your app.
Should my app have its own light and dark toggle?
Only for when it's used outside Performance Hub. Inside it, Performance Hub decides; hide your
toggle once phApp.onHostReady() runs.
Performance Hub's loading screen stays up too long, or lifts too early
By default it lifts when your page has loaded. If the first view needs data first, add
data-ph-ready="manual" to <html> and call phApp.ready() when it's drawn.
How do I take screenshots in a particular theme?
Add ?phTheme=light or ?phTheme=dark to the app's URL.
Which optional scripts do I need?
Only the ones a page uses: ph-app-charts.js for charts, KPI tiles and heatmaps; then calendar,
editor, maps, data grid or sortable for those modules. Maps is the largest, at about 284 KB. See
Reference.
A table or a data grid?
A table for up to a few hundred rows: it's plain HTML, prints well and sorts and pages itself. A data grid for thousands of rows or inline editing.
Will updates break my app?
No. Everything under /assets/app-kit/v1/ only gains classes, options and helpers. A change that
could break apps would be published as v2, at a new URL.
Is there a live example?
Yes: a plain page and the optional modules.