Getting started
On this page
The PH App Kit is a hosted stylesheet and script. Add them to a page and you can use every kit
component with plain HTML classes; there's nothing to install or build. React apps use the
ph-app-kit-react package as well (see React).
Add the kit to a page
Put these tags in the page's <head>:
<link rel="stylesheet" href="https://app.performancehub.co/assets/app-kit/v1/ph-app.css" />
<script defer src="https://app.performancehub.co/assets/app-kit/v1/ph-app.js"></script>
ph-app.csshas the font, colour tokens, light and dark mode, and every component.ph-app.jsmakes interactive components work (tabs, menus, sortable tables, dialogs), adds thewindow.phApphelpers, and connects the app to Performance Hub.
Add optional scripts after ph-app.js, and only on the pages that use them:
| Script | Adds | Size (gzipped) |
|---|---|---|
ph-app-charts.js | Charts, KPI tiles, heatmaps | 76 KB |
ph-app-calendar.js | Calendar | 79 KB |
ph-app-editor.js | Rich text editor | 138 KB |
ph-app-maps.js | Maps | 284 KB |
ph-app-datagrid.js | Data grid | 15 KB |
ph-app-sortable.js | Drag and drop | 16 KB |
<script defer src="https://app.performancehub.co/assets/app-kit/v1/ph-app-charts.js"></script>
The v1 in the address is the kit's version. It stays backward compatible: classes are added
but never renamed or removed, so pages keep working as the kit improves.
Your first page
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Store orders</title>
<link rel="stylesheet" href="https://app.performancehub.co/assets/app-kit/v1/ph-app.css" />
<script defer src="https://app.performancehub.co/assets/app-kit/v1/ph-app.js"></script>
<script defer src="app.js"></script>
</head>
<body>
<main class="ph-page">
<header class="ph-page-header">
<div>
<h1 class="ph-page-title">Store orders</h1>
<p class="ph-page-description">Orders across all stores</p>
</div>
<div class="ph-page-actions">
<button type="button" class="ph-btn" id="export">Export CSV</button>
<button type="button" class="ph-btn ph-btn--primary">Add customer</button>
</div>
</header>
<section class="ph-card" id="content"></section>
</main>
</body>
</html>
Kit scripts are deferred, so run your own code from a deferred script placed after them (as
app.js is above) or on DOMContentLoaded:
document.addEventListener('DOMContentLoaded', async () => {
const orders = await phApp.fetchJSON('api/orders');
phApp.toast(`Loaded ${phApp.format.number(orders.length)} orders`);
});
Light and dark mode
There's nothing to set up. The kit picks the mode before the first paint:
- Inside Performance Hub: the app follows the user's light or dark choice, and switches live when they change it.
- In a plain browser tab: the app follows the operating system's setting.
- For testing and screenshots: add
?phTheme=lightor?phTheme=darkto the page address.
Use colour tokens (rgb(var(--ph-surface))) in your own CSS rather than fixed colours, so your
additions switch too. See Theming.
URLs inside Performance Hub
An app doesn't always open at the root of its address, so links and API calls must be relative:
phApp.fetchJSON('api/customers'); // right: relative to the app
fetch('/api/customers'); // wrong: escapes the app's path
phApp.url('/api/customers'); // turns an absolute path into the app's own
See Performance Hub integration for the rest of what changes inside Performance Hub.
React apps
React apps link the same stylesheet in index.html, then wrap the app in PhAppProvider:
import { createRoot } from 'react-dom/client';
import 'ph-app-kit-react/styles.css';
import { PhAppProvider } from 'ph-app-kit-react';
import App from './App';
createRoot(document.getElementById('root')!).render(
<PhAppProvider>
<App />
</PhAppProvider>,
);
See React for installing the package, the Tailwind preset and the component list.
Checklist before you share an app
- The page has
<html lang="en">, a<title>, the viewport meta tag and oneh1. - It looks right in both modes (
?phTheme=lightand?phTheme=dark) and at 360px wide. - Every view that loads data shows a skeleton, then the content, an empty state or an error with a Try again button.
- Links and API calls are relative.
- It follows the guidelines for copy, keyboard use and speed.