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