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.css has the font, colour tokens, light and dark mode, and every component.
  • ph-app.js makes interactive components work (tabs, menus, sortable tables, dialogs), adds the window.phApp helpers, and connects the app to Performance Hub.

Add optional scripts after ph-app.js, and only on the pages that use them:

ScriptAddsSize (gzipped)
ph-app-charts.jsCharts, KPI tiles, heatmaps76 KB
ph-app-calendar.jsCalendar79 KB
ph-app-editor.jsRich text editor138 KB
ph-app-maps.jsMaps284 KB
ph-app-datagrid.jsData grid15 KB
ph-app-sortable.jsDrag and drop16 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=light or ?phTheme=dark to 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 one h1.
  • It looks right in both modes (?phTheme=light and ?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.