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.
| What | What happens |
|---|---|
| Theme | The app follows the user's light or dark choice, and switches live when they change it |
| Keyboard shortcuts | Performance Hub's shortcuts keep working while focus is in the app |
| Dialogs | Kit dialogs and drawers dim the whole Performance Hub window, not just the frame |
| Loading | Performance Hub's loading screen lifts as soon as the app's page has rendered |
| Navigation | The 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()andphApp.onThemeChange(). - Add
?phTheme=darkor?phTheme=lightto 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:
| Shortcut | Performance Hub action |
|---|---|
| Ctrl+K / ⌘K | Search |
| Ctrl+J / ⌘J | Club selector |
| Ctrl+I / ⌘I | Help panel (in rich text editors, it stays italic) |
| Alt+Ctrl+L / ⌥⌘L | Switch 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();
Navigation
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')andphApp.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.
Related
- JavaScript API: the connection functions
- Theming
- Guidelines