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 dependency | Version |
|---|---|
react, react-dom | 18 |
@mui/material | 5 |
@emotion/react, @emotion/styled | 11 |
chart.js | 4 (for charts) |
lucide-react | 0.503 or later, before 1.0 (for icons) |
@mdi/js, @mdi/svg | 7 (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:
| Module | Packages |
|---|---|
| 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 |
| Maps | maplibre-gl |
| Data grid | @tanstack/react-virtual |
| Drag and drop | sortablejs |
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
| Area | Exports |
|---|---|
| Layout | Card, ActionTile, Toolbar, SearchField, SettingsLayout, OverviewCard, InfoRow, MetricBar |
| Data | DataTable, FilterChip, FilterTextChip, StatCard, DeltaBadge, StatusChip, RunStatusList, DayTimeline, JsonViewer, CopyableId |
| Forms | StyledButton, StyledTextField, StyledSelect, StyledCheckbox, ToggleSwitch, LabeledToggle, FormField, FieldLabel, SettingSlider, SegmentedToggle, TimezonePicker |
| Dates | DateRangeSelect, DateSelect, TimeSelect, MonthRangeSelect |
| Overlays | StyledDialog, FormDialog, FormDrawer, DrawerSection, DrawerShell, StyledTabs, StyledTab |
| Feedback | useToast, Callout, Skeleton and the page skeletons (TableSkeleton, DashboardPageSkeleton, …) |
| Live data | LiveRefreshSelect, useLiveRefresh, useLiveCountdown, live |
| Icons | MdiIcon for Material Design Icons; lucide-react for everything else |
| Helpers | url, wsUrl, basePath, fetchJSON, format, csv, downloadCsv, exportFilename, getChartSeriesColors, getChartColors, withAlpha |
| Theme and connection | usePhTheme() ('light' or 'dark'), usePhBridge() (embedded(), onHostReady(), navigate(), ready()) |
| Entry point | Exports |
|---|---|
ph-app-kit-react/charts | TimeSeriesChart, BarChart, DonutChart, GaugeChart, RankedBars, HeatmapCalendar, KpiCard, Sparkline |
ph-app-kit-react/calendar | EventCalendar |
ph-app-kit-react/editor | RichTextEditor, RichTextView |
ph-app-kit-react/maps | MapView |
ph-app-kit-react/datagrid | DataGrid |
ph-app-kit-react/sortable | SortableList |
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 withph-*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 fromph-app.cssandstyles.css. - Build clickable things from kit components, not bare
<button>s with Tailwind classes: a grid of things to open isActionTile, a button isStyledButton, a filter isFilterChiporFilterTextChip. - Load charts, calendars, editors and maps with
React.lazyandSuspense, 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 buildprints 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), neverfetch('/api/…'). - Type everything (
Column<Customer>[],fetchJSON<Summary>('api/summary')) and keepstricton.
Related
- Getting started
- JavaScript API: the plain JS helpers
- Charts