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

  1. 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).
  2. 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-ancestors to your registered origins, and loads the component's assets from Payroo's assets origin.
  3. 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.
  4. 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.