Widget API Message Types

sunc-widget:loadScrap

Loads a test result from the provided scrapId and accessKey.

type LoadScrapPayload = {
  scrapId: string;
  key: string;
};

Parameters

Parameter	Description
scrapId	The unique ID of the test result.
key	The access key required to view the test.

Example

iframe.contentWindow.postMessage({
  type: "sunc-widget:loadScrap",
  payload: {
    scrapId: "abc123XYZ",
    key: "someAccessKey"
  }
}, "https://sunc.rubis.app");

---

sunc-widget:setTheme

Updates the colour theme of the widget to match your branding. Any missing fields will fall back to defaults.

type ThemePayload = {
  dark?: string;
  light?: string;
  lighter?: string;

  sunc?: string;
  suncLighter?: string;

  grey?: string;
  lightText?: string;

  success?: string;
  failure?: string;

  useDarkLogo?: boolean;
};

Parameters

Parameter	Type	Description	Default
dark	string	Primary background colour for the entire widget.	#12121c
light	string	The secondary colour used for function cards and the summary on the right.	#1b1b2a
lighter	string	Colour used for the information bar at the top.	#1c1b28
sunc	string	Brand accent colour to be used by the info text, circle stroke and passed amount.	#b7a0f6
suncLighter	string	Used for hover effects, like the Numelon link at the bottom.	#d1b9ff
grey	string	Used for muted UI elements like search input icons, placeholder text, and metadata titles in the summary area.	#aaaaaa
lightText	string	Main readable text colour - used in the widget "Test Result" title, percentage label inside ring, and metadata values in the summary area and button text.	#e0e0e0
success	string	Colour used to indicate passed tests.	#22c55e
failure	string	Colour used for general failures, notably in the list of functions but also for widget errors and the "x tests failed" text.	#ef4444
useDarkLogo	string	Whether to use a light-friendly (dark) version of the sUNC logo. Set to false if you are using a light theme.	true

Clarification on colour names

You may have noticed that the colour names (like dark, light, lighter) do not follow typical design conventions like primary/secondary/tertiary. In hindsight, they might seem a bit misleading at first glance - however they are named based on where they are used in the widget, not their strict visual roles.

The image below visually presents parts of the SEW with the colour names they are associated with - and the names start to make much more sense. For example, dark corresponds to the deepest background colour in the very background of the page, light is the colour of the main title bar at the top where the sUNC logo, and lighter is literally a slightly lighter colour for the information bar below the title bar, et cetera:

Logo Comparison

The sUNC logo shown in the top left of the widget can be customised depending on whether you intend to use a light theme or a dark theme. This is important to get right, otherwise you will have horrible contrast in the title bar of the widget.

If useDarkLogo is omitted entirely, then the widget defaults to true - it uses the dark logo by default.

useDarkLogo: false

When useDarkLogo is set to false, a light variant is used. This is perfect for when the background is dark as it provides enough contrast.

Use this when you have a dark theme.

useDarkLogo: true

When useDarkLogo is set to true, a dark variant is used. This is perfect for when the background is light as it provides enough contrast.

Use this when you have a light theme.

Examples

Example 1

Preview of the Creamy Pink theme

Not Initialised

Spoofed

Result

iframe.contentWindow.postMessage({
    type: "sunc-widget:setTheme",

    payload: {
        dark: "#fff0f5",
        light: "#fffbfc",
        lighter: "#ffeeee",

        sunc: "#ff6aa0",
        suncLighter: "#ff9abe",

        grey: "#888",
        lightText: "#444",

        success: "#44c26a",
        failure: "#e74c3c",

        useDarkLogo: true // (1)
    }
}, "https://sunc.rubis.app");

1. Set this to true when using light background colours.

Example 2

Preview of the Electric Yellow theme

Not Initialised

Spoofed

Result

iframe.contentWindow.postMessage({
    type: "sunc-widget:setTheme",

    payload: {
        dark: "#0f0f12",
        light: "#1a1a20",
        lighter: "#26262f",

        sunc: "#ffe600",
        suncLighter: "#fff36b",

        grey: "#999999",
        lightText: "#eeeeee",

        success: "#4caf50",
        failure: "#ff4b5c",

        useDarkLogo: false // (1)
    }
}, "https://sunc.rubis.app");

1. Set this to false when using dark background colours.

Example 3

Preview of the Default theme

Not Initialised

Spoofed

Result

iframe.contentWindow.postMessage({
    type: "sunc-widget:setTheme",

    payload: {} // (1)
}, "https://sunc.rubis.app");

1. To revert back to the default theme, one may simply pass a message with an empty payload using the postMessage API.