Embedding the frame shell
Every component also runs inside a Payroo-origin iframe: Payroo hosts the UI, your page hosts the frame. Choose it when you do not want to ship React, when your stack is not React, or when you want Payroo's own styling and updates without a dependency bump. Both shells run on the same session and emit the same events.
React
import { PayrooFrame } from '@payroo-group/embedded-react';
<PayrooProvider adapter={adapter} theme={theme} onEvent={track}>
<PayrooFrame
component="employees"
title="Employees"
onError={(code, message) => console.warn(code, message)}
/>
</PayrooProvider>;
| Prop | Meaning |
|---|---|
component |
the component id: calendar, company-setup, employees, run-payroll, payrun-history, self-payslips. Employee self-onboarding is not framed by you: the invitation link opens Payroo's own landing page, which hosts it |
props |
the component's own props, passed into the frame (serialisable values only) |
title |
the iframe's accessible title |
onMessage(m) |
every message from the frame, with its nonce, if you want the raw stream |
onError(code, message) |
frame_blocked, the code a frame.error message carries, session errors |
controllerRef |
a handle for host-side commands (for example opening the approval dialog from your own button) |
readyTimeoutMs |
how long to wait for frame.ready before reporting frame_blocked (default 5000) |
Plain HTML
npm install @payroo-group/embedded-loader # ESM, plus dist/payroo-embed.iife.js for a script tag
<div id="payroll"></div>
<script type="module">
import { PayrooEmbed, preconnect } from '@payroo-group/embedded-loader';
preconnect('https://sandbox.payroo.com.au');
const handle = PayrooEmbed.mount({
container: '#payroll',
component: 'company-setup',
getSession: () => fetch('/payroll/session', { method: 'POST' }).then((r) => r.json()),
onSessionExpiring: () => fetch('/payroll/session', { method: 'POST' }).then((r) => r.json()),
theme: { colorPrimary: '#1d3557' },
props: {},
onEvent: (name, payload) => console.log(name, payload),
onError: (code, message) => console.warn(code, message),
});
// handle.update(props), handle.setTheme(theme), handle.unmount(); handle.controller resolves to the frame controller
</script>
Serve dist/payroo-embed.iife.js from your own site for a page without a bundler; it exposes window.PayrooEmbed with the same mount. The loader accepts only the options above (getBootstrap and readyTimeoutMs in addition) and rejects anything else; the session object goes to the frame as Payroo returned it.
How it works
- The runtime asks your session for a bootstrap: a 60-second token bound to one component and the page's origin (
POST /sessions/{id}/bootstraps, done for you). - It loads the frame document from the Payroo API origin with that bootstrap. The document verifies the signature against Payroo's published keys, sets
frame-ancestorsto your registered origins, and loads the component's assets from Payroo's assets origin. - The frame and your page talk over a nonce-checked message channel:
frame.ready,frame.mounted,frame.resize(the frame reports its height; the runtime sizes the iframe), then the business events as they happen. A session that nears expiry asks the host for a new one through the same channel. - Secure fields and confirmation dialogs are nested Payroo frames inside the component frame; nothing about them changes for you.
Choosing a shell
| Native React | Frame | |
|---|---|---|
| Styling | your tokens on your DOM | your tokens inside Payroo's layout |
| Stack | React 18.2+ | anything |
| Updates | you bump the package | Payroo deploys |
| CSP | connect-src and frame-src for the API origin |
frame-src only |
| CORS | your origin must be registered | not involved; the frame calls the API from Payroo's origin |
| Mixing | yes: a page can hold native components and frames side by side on the same session | yes |
What you should see
The iframe appears sized to its content within a second (frame.ready, frame.mounted); the component behaves exactly as its native twin; your onEvent receives the same event names with shell: 'frame'. A missing frame-src or an unregistered origin produces frame.blocked and a blocked state in place of the component.