Performance Hub integration

On this page

When Performance Hub shows your app, it shows it in a frame inside the Performance Hub window. ph-app.js connects the two automatically, so the app looks and behaves like part of Performance Hub. There's nothing to wire up: load the kit and these work.

WhatWhat happens
ThemeThe app follows the user's light or dark choice, and switches live when they change it
Keyboard shortcutsPerformance Hub's shortcuts keep working while focus is in the app
DialogsKit dialogs and drawers dim the whole Performance Hub window, not just the frame
LoadingPerformance Hub's loading screen lifts as soon as the app's page has rendered
NavigationThe app can open Performance Hub pages

Opened on its own in a browser tab, the app follows the device's light or dark setting, and nothing else changes.

Theme

Performance Hub tells the app its theme before the first paint, so there's no flash of the wrong mode. The kit sets class="dark" or class="light" and color-scheme on <html>, and every kit component, chart, calendar and map updates itself.

  • Don't show your own theme toggle inside Performance Hub. Hide it once phApp.onHostReady() runs.
  • For your own code that depends on the theme, use phApp.theme() and phApp.onThemeChange().
  • Add ?phTheme=dark or ?phTheme=light to the app's URL to force a mode, for screenshots and testing.

Keyboard shortcuts

These belong to Performance Hub. The kit passes them up while focus is in the app, so never bind them yourself:

ShortcutPerformance Hub action
Ctrl+K / ⌘KSearch
Ctrl+J / ⌘JClub selector
Ctrl+I / ⌘IHelp panel (in rich text editors, it stays italic)
Alt+Ctrl+L / ⌥⌘LSwitch between light and dark

For the app's own shortcuts, use single keys when focus isn't in a field (/ to search, n for new), or Shift with a letter. Show them with <kbd>.

Dialogs

When a kit dialog or drawer opens, Performance Hub dims its own window around the frame, so the dialog looks like it belongs to the whole page. Clicking the dimmed area closes the dialog, unless it has data-ph-static. This works for .ph-dialog, .ph-drawer and phApp.dialog.confirm(), and for the React dialogs and drawers.

Loading

Performance Hub shows a loading screen until the app says it's ready. By default the kit does this when the page has loaded. If your app draws its first view only after data arrives, delay it:

<html lang="en" data-ph-ready="manual">
await loadFirstView();
phApp.ready();

phApp.navigate('/members') asks Performance Hub to open one of its own pages. It returns false when the app isn't inside Performance Hub, so you can fall back to a link.

Knowing you're inside Performance Hub

phApp.onHostReady((host) => {
  document.querySelector('#theme-toggle').hidden = true;
});

if (phApp.embedded()) { /* inside Performance Hub */ }

phApp.host() returns { host: 'performance-hub', features, origin } once connected, and null before that or outside Performance Hub. Being in a frame alone doesn't count: the app is embedded only once Performance Hub has connected to it.

URLs

An app doesn't always open at the root of its address. URLs that start with / point at the root of the whole site and break.

  • Use relative URLs: api/items, assets/app.css.
  • Or build them with phApp.url('/api/items') and phApp.wsUrl('ws').
  • phApp.fetchJSON() does this for you.
  • In React with Vite, set base: './', and use a hash router for more than one or two views.