Embedding the React package
@payroo-group/embedded-react renders Payroo's components in your own DOM, styled by your tokens, talking to Payroo on a session your server mints. One provider, then components where you want them.
Install
npm install @payroo-group/embedded-react @payroo-group/embedded-core
React 18.2 or 19. The components are client components: in Next.js, mount them from a file marked 'use client'.
Adapter and provider
import { createServerSessionAdapter } from '@payroo-group/embedded-core';
import { PayrooProvider } from '@payroo-group/embedded-react';
const adapter = createServerSessionAdapter({
mode: 'staging', // 'staging' | 'production' | 'mock'
capabilities: ['v1-embedded'],
apiBaseUrl: 'https://sandbox.payroo.com.au/api/v1/embedded',
sessionUrl: '/payroll/session', // your route: POST, returns the Session object as Payroo returned it
});
<PayrooProvider
adapter={adapter}
theme={{ colorPrimary: '#1d3557', radiusMd: '10px', fontFamilyBody: 'Inter, sans-serif' }}
onEvent={(e) => track(e.name, e.payload)}
onThemeIssues={(issues) => console.warn(issues)}
>
…
</PayrooProvider>;
The adapter calls your session route on mount and again when refreshAfter passes or a 401 arrives; components under the provider show a skeleton until the session exists and a blocked state when it cannot be obtained. Pass through to your route the user's identity and the company they are working on; the route decides the components and scopes (see Authentication and sessions).
Components
| Component | Session type, scopes, component id | Props |
|---|---|---|
CompanySetupChecklist |
employer, company:read, company-setup |
onSelectStep(step), version to force a reload |
BankAccountForm |
employer, company:write, company-setup |
onSaved(view) |
AtoConnection |
employer, company:write, company-setup |
onSaved(state) |
SuperFund |
employer, company:write, company-setup |
frame only (SuperAPI's widget); see the frame guide |
Employees |
employer, employees:read/write, employees |
list, add and record in one; or compose EmployeeList, EmployeeForm (onSaved(employee, invitation?), onCancel), EmployeeRecord yourself |
SelfOnboarding |
employee session from an invitation, self:onboarding |
onCompleted() |
RunPayroll |
employer, payruns:read/write/lodge, documents:read, run-payroll |
payrunId to open a specific run; onCreated(payrun), onApproved(), onReopened(), onLodging(operationId), onOutcome('accepted' | 'rejected' | 'needs_attention') |
PayrunReview |
employer, payruns:read/write |
the approval review and confirmation for one run |
PayrunHistory |
employer, payruns:read, documents:read, payrun-history |
financialYear, state, onOpen(summary), detail: 'inline' | 'none' |
Calendar |
employer, calendar:read, calendar |
month (YYYY-MM), onMonthChange(month) |
SelfPayslips |
employee, self:payslips, self-payslips |
onOpen(payslip) |
PayrooFrame |
any | renders any component in a Payroo-origin frame; see Embedding the frame shell |
Helpers: SessionGate (render children only with a live session), useEmbeddedQuery (a typed fetch on the session), money and dateAu formatters, Skeleton, ErrorNotice, Badge.
Theme
Named tokens only; anything else is ignored:
colorPrimary, colorPrimaryAccent, colorOnPrimary, colorBody, colorOnBody, colorSurface, colorOnSurface, colorSuccess, colorOnSuccess, colorWarning, colorOnWarning, colorDanger, colorOnDanger, colorInfo, colorOnInfo, colorBorder, radiusSm, radiusMd, radiusLg, fontFamilyBody, fontFamilyHeading, fontSizeBase, spacingUnit, density (compact or regular), focusRing, shadow.
A colour pair under 4.5:1 contrast falls back to the default and is reported through onThemeIssues. Fonts come from an allowlist; inside frames they load only from Payroo's assets origin. The same tokens set on your partner record (theme.colorPrimary) brand the invitation e-mail and the self-onboarding landing.
Content-Security-Policy
connect-src https://sandbox.payroo.com.au (the API, for the native shell) and frame-src https://sandbox.payroo.com.au (secure fields and confirmation dialogs). Production hosts are announced with your production record.
What you should see
With a sandbox session, CompanySetupChecklist renders the five steps with their state; Employees lists the company's employees and adds one through secure fields; RunPayroll creates a draft and takes it through approval and lodgement with Payroo's dialogs appearing at the right moments; every action appears in onEvent.
Errors you may see
| Where | Meaning | Next action |
|---|---|---|
| blocked state after mount | your session route failed or returned 401/403 |
check the route's response body; the code tells you which mint rule refused |
frame.blocked event |
a secure field or dialog could not load | add frame-src for the API origin; register the page's origin |
| theme issue reported | a token pair fails contrast | adjust the colours |