React

On this page

ph-app-kit-react is the Performance Hub React kit: the same components Performance Hub's own screens use, built on MUI 5 and Tailwind, plus React versions of the charts and optional modules. PhAppProvider sets up light and dark mode, toasts and the connection to Performance Hub.

Install

The package is published with the kit. latest.json names the current file:

KIT=https://app.performancehub.co/assets/app-kit/v1
FILE=$(curl -fsS "$KIT/react/latest.json" | node -p "JSON.parse(require('fs').readFileSync(0)).file")
mkdir -p vendor && curl -fsS -o "vendor/$FILE" "$KIT/react/$FILE"
npm install "./vendor/$FILE"

latest.json also has the file's integrity (SHA-512) and the peer dependency versions. Run the same steps to update.

Peer dependencyVersion
react, react-dom18
@mui/material5
@emotion/react, @emotion/styled11
chart.js4 (for charts)
lucide-react0.503 or later, before 1.0 (for icons)
@mdi/js, @mdi/svg7 (for MdiIcon)

The calendar, editor, maps, data grid and drag-and-drop components need their libraries too. Install the packages for the modules you use:

ModulePackages
Calendar@fullcalendar/core, @fullcalendar/daygrid, @fullcalendar/interaction, @fullcalendar/list, @fullcalendar/react, @fullcalendar/timegrid
Rich text editor@tiptap/core, @tiptap/extensions, @tiptap/pm, @tiptap/react, @tiptap/starter-kit, dompurify
Mapsmaplibre-gl
Data grid@tanstack/react-virtual
Drag and dropsortablejs

Every package is listed under peerDependencies in react/latest.json, with its version range. See Reference for the tested versions.

Wiring

Keep the hosted stylesheet in index.html; it sets the font, tokens and the first-paint theme:

<link rel="stylesheet" href="https://app.performancehub.co/assets/app-kit/v1/ph-app.css" />
// main.tsx
import { createRoot } from 'react-dom/client';
import 'ph-app-kit-react/styles.css';
import './index.css';
import { PhAppProvider } from 'ph-app-kit-react';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <PhAppProvider>
    <App />
  </PhAppProvider>
);
/* index.css: no @tailwind base. ph-app.css is the base, and ph-app-kit-react/styles.css adds
   the resets Tailwind's utilities expect (plain buttons, borders that show, bare lists). */
@tailwind components;
@tailwind utilities;
// tailwind.config.cjs: your own utilities use the same ph-* colour tokens
module.exports = {
  presets: [require('ph-app-kit-react/tailwind-preset')],
  content: ['./index.html', './src/**/*.{ts,tsx}'],
};
// vite.config.ts: keep asset URLs relative, so they work wherever the app opens
export default defineConfig({ base: './', plugins: [react()] });

A first view

import { useEffect, useState } from 'react';
import { Card, DataTable, StyledButton, Callout, TableSkeleton, fetchJSON, format, type Column } from 'ph-app-kit-react';

type Customer = { id: number; name: string; orders: number };

const columns: Column<Customer>[] = [
  { key: 'name', label: 'Customer', render: (customer) => customer.name },
  { key: 'orders', label: 'Orders', align: 'right', render: (customer) => format.number(customer.orders) },
];

export function Customers() {
  const [customers, setCustomers] = useState<Customer[] | null>(null);
  const [error, setError] = useState<string | null>(null);
  const load = () => fetchJSON<Customer[]>('api/customers').then(setCustomers, (e) => setError(e.message));
  useEffect(() => void load(), []);

  if (error) return <Callout severity="error" action={<StyledButton onClick={load}>Try again</StyledButton>}>{error}</Callout>;
  if (!customers) return <TableSkeleton />;
  return (
    <Card title="Customers" description={`${customers.length} customers`}>
      <DataTable rows={customers} columns={columns} rowKey={(customer) => String(customer.id)} />
    </Card>
  );
}

Components

AreaExports
LayoutCard, ActionTile, Toolbar, SearchField, SettingsLayout, OverviewCard, InfoRow, MetricBar
DataDataTable, FilterChip, FilterTextChip, StatCard, DeltaBadge, StatusChip, RunStatusList, DayTimeline, JsonViewer, CopyableId
FormsStyledButton, StyledTextField, StyledSelect, StyledCheckbox, ToggleSwitch, LabeledToggle, FormField, FieldLabel, SettingSlider, SegmentedToggle, TimezonePicker
DatesDateRangeSelect, DateSelect, TimeSelect, MonthRangeSelect
OverlaysStyledDialog, FormDialog, FormDrawer, DrawerSection, DrawerShell, StyledTabs, StyledTab
FeedbackuseToast, Callout, Skeleton and the page skeletons (TableSkeleton, DashboardPageSkeleton, …)
Live dataLiveRefreshSelect, useLiveRefresh, useLiveCountdown, live
IconsMdiIcon for Material Design Icons; lucide-react for everything else
Helpersurl, wsUrl, basePath, fetchJSON, format, csv, downloadCsv, exportFilename, getChartSeriesColors, getChartColors, withAlpha
Theme and connectionusePhTheme() ('light' or 'dark'), usePhBridge() (embedded(), onHostReady(), navigate(), ready())
Entry pointExports
ph-app-kit-react/chartsTimeSeriesChart, BarChart, DonutChart, GaugeChart, RankedBars, HeatmapCalendar, KpiCard, Sparkline
ph-app-kit-react/calendarEventCalendar
ph-app-kit-react/editorRichTextEditor, RichTextView
ph-app-kit-react/mapsMapView
ph-app-kit-react/datagridDataGrid
ph-app-kit-react/sortableSortableList

Each component page in these docs shows its React equivalent.

Rules for React apps

  • Use the kit components first, then the rest of @mui/material (Autocomplete, Stepper, Accordion, …), which picks up the same theme. Other libraries are fine for anything neither covers: theme them with ph-* classes and load them lazily if they're heavy.
  • Colours come from ph-* Tailwind classes (bg-ph-surface, text-ph-secondary, border-ph-grayOutline) or the MUI theme, never hex.
  • Don't add @tailwind base: it restyles the kit's headings, links and lists. The base comes from ph-app.css and styles.css.
  • Build clickable things from kit components, not bare <button>s with Tailwind classes: a grid of things to open is ActionTile, a button is StyledButton, a filter is FilterChip or FilterTextChip.
  • Load charts, calendars, editors and maps with React.lazy and Suspense, with a skeleton of the same height as the fallback. Import the entry points above only from those lazy modules.
  • Keep the first load within 200 KB of JavaScript, gzipped. npx vite build prints the sizes.
  • Routing: no router for one or two views (use StyledTabs). For more, use a hash router (createHashRouter); nested browser paths break relative asset URLs.
  • Call APIs with fetchJSON('api/…') (relative), never fetch('/api/…').
  • Type everything (Column<Customer>[], fetchJSON<Summary>('api/summary')) and keep strict on.