Modal Customisation

Visual Customisation Theme

GatewayEmbeddedSignup.init({
  publishableKey: 'pb_…',
  theme: GatewayTheme.Purple,  // GatewayTheme.Blue (default) | Orange | Purple
});

The theme sets the colour of modal buttons and the selected-card border.

Logo

GatewayEmbeddedSignup.init({
  publishableKey: 'pb_…',
  logoUrl: 'https://yourapp.com/logo.png',  // top-left of the connection-type modal
});

`logoUrl` value	Result
omitted / `undefined`	Connexease logo
`'https://…'` or `'http://…'`	Your logo
whitespace-only (`' '`)	No logo
any non-`http(s)` value	Falls back to Connexease logo

Custom logoUrlvs. a Default Connexease logo:

Heads-up: the logo is loaded by the browser as a normal <img>. If your image host has hotlink protection or restrictive CORS/Referer rules, the logo may load on one domain but break on another. Host the logo somewhere that allows cross-origin embedding (your own domain or a public CDN).

Custom CSS URL

Connexease Embedded Signup SDK ships with its own default modal styles. The modal works without any additional setup. If a customer wants to fully restyle the SDK-owned modal from their own application, pass a customer-owned stylesheet with customCssUrl.

Usage

Host a CSS file from the customer application or CDN:

https://customer.example/your-modal-theme.css

Then pass it to init():

import { GatewayEmbeddedSignup } from '@connexease/gateway-embedded-signup';

const widget = GatewayEmbeddedSignup.init({
  publishableKey: 'pb_...',
  customCssUrl: '/your-modal-theme.css',
});

When a relative URL is used, it is resolved from the customer’s own origin. For example, if the customer panel runs at https://customer.example/settings, then /your-modal-theme.css resolves to:

https://customer.example/your-modal-theme.css

How It Works

The SDK first injects its bundled modal CSS into the modal Shadow DOM. Then it loads the customer CSS file from customCssUrl in the same Shadow DOM as a link rel="stylesheet". The order matters: because the customer stylesheet is loaded after the SDK stylesheet, it can override the same selectors.

<style>
  /* SDK default modal CSS */
</style>
<style data-gw-custom-css-gate>
  :host { visibility: hidden; }
</style>
<link rel="stylesheet" href="/your-modal-theme.css" data-gw-custom-css>

The gate style is added only when customCssUrl is provided. The modal stays hidden until the custom CSS file finishes loading, so the default SDK modal design does not flash briefly before the customer design appears. If the CSS file fails to load or takes too long, the SDK removes the gate and continues with the default/token design so onboarding is not blocked.

Example CSS

:host {
  --gw-primary: #0B7A4E;
  --gw-primary-strong: #075C3A;
  --gw-primary-soft: #E7F5EE;
  --gw-radius-lg: 6px;
  --gw-radius-md: 6px;
  --gw-radius-sm: 6px;
  --gw-font-family: Inter, ui-sans-serif, system-ui, sans-serif;
}

.modal {
  max-width: 900px;
  min-height: 420px;
  border-radius: 4px;
  border: 1px solid rgba(15, 42, 30, 0.12);
  box-shadow: 0 24px 80px rgba(15, 23, 42, 0.18);
}

.title {
  font-size: 24px;
  color: #0F2A1E;
}

.card {
  background: #FFFFFF;
  border-color: #A8DCC2;
}

.card--selected {
  background: #E7F5EE;
  border-color: #0B7A4E;
}

.btn--primary {
  background: #0B7A4E;
  color: #FFFFFF;
}

Supported Styling Selectors

The customer stylesheet runs inside the SDK modal Shadow DOM, so it can target the modal selectors listed below.

Selector	Description
`:host`	The SDK modal Shadow DOM host. Use it to override `--gw-*` CSS variables.
`[hidden]`	Internal attribute used by the SDK to hide panels that should not be visible. Do not override this selector.
`.overlay`	Full-screen backdrop behind the modal.
`.modal`	Main modal container. Width, height, padding, border, radius, background, and shadow can be changed here.
`.modal--wide`	Additional class used by wider status modals such as error and warning views.
`.close-x`	Top-right X close button.
`.close-x:hover`	Hover state of the X close button.
`.close-x:active`	Pressed state of the X close button.
`.close-x::before`	Pseudo element that expands the close button hit area.
`.modal-header`	Header area that contains the logo and title alignment.
`.modal-logo-wrap`	Wrapper for the default Connexease logo or customer logo.
`.modal-logo-wrap svg`	Targets the default Connexease SVG logo.
`.modal-logo-img`	Customer logo image rendered through `logoUrl` or `assets.logo`.
`.title`	Main modal heading.
`.subtitle`	Modal description text.
`.section-label`	Small label above the connection type cards.
`.icon-wrap`	Wrapper for success, error, and warning icons.
`.icon-wrap svg`	SDK default success/error/warning SVG icons.
`.icon-wrap img`	Customer status icons from `assets.successIcon`, `assets.errorIcon`, or `assets.warningIcon`.
`.footer`	Bottom action area containing timer and buttons.
`.footer-left`	Left side of the footer, usually where the session timer is rendered.
`.footer-actions`	Wrapper around footer action buttons.
`.footer .session-timer`	Footer-specific timer styling.
`.btn`	Base selector for standard modal buttons.
`.btn:active`	Pressed state for standard buttons.
`.btn:disabled`	Disabled button state.
`.btn--primary`	Primary action button, such as the Connect button.
`.btn--primary:hover`	Hover state of the primary action button.
`.btn--secondary`	Secondary action button, such as Close or Cancel.
`.btn--secondary:hover`	Hover state of the secondary action button.
`.session-timer`	Text that displays the remaining session time.
`.session-timer span`	Numeric countdown value inside the timer.
`.session-timer--warn`	Warning state added when the session is close to expiring.
`.spinner`	Small loading spinner used inside the restart button.
`.card:focus-visible`	Keyboard focus ring for connection type cards.
`.btn:focus-visible`	Keyboard focus ring for buttons.
`.close-x:focus-visible`	Keyboard focus ring for the X close button.

Selector	Description
`.cards`	Grid wrapper for Cloud API and Coexistence cards.
`.cards--single`	Added when only one connection type card is shown.
`.card`	Each connection type selection card.
`.card:hover:not(.card--selected)`	Hover state for an unselected card.
`.card--selected`	Currently selected connection type card.
`.card-title`	Card title, such as Cloud API or Coexistence.
`.card-desc`	Short card description.
`.cloud-api-info`	Information box shown when Cloud API is selected.
`.coex-info`	Information box shown when Coexistence is selected.
`.coex-info-title`	Heading inside the Cloud API or Coexistence information box.
`.coex-info-list`	Wrapper for the list inside the information box.
`.coex-info-list li`	Each list item in the information box.
`.coex-info-list li + li`	Spacing between information list items.
`.coex-info-list li::marker`	Bullet marker colour for information list items.

Selector	Description
`.warning-banner`	Warning banner shown when the Meta popup restart action is ready.
`.btn--restart`	Restart button before it is ready.
`.btn--restart.ready`	Restart button after it becomes clickable.
`.btn--restart.ready:hover`	Hover state of the ready restart button.
`.btn--restart.ready .spinner`	Spinner inside the restart button, hidden when restart is ready.
`.processing-wrap`	Wrapper for the spinner and label shown while the connect request is running.
`.processing-spinner`	Large spinner shown while the connect request is running.
`.processing-label`	Text shown under the processing spinner.

CSS Changes Appearance, Not HTML Structure

customCssUrl can change the modal appearance:

colours
fonts
spacing
borders and radius
shadows
modal width and height
button and card styling
success/error/warning icon presentation
responsive behaviour

It cannot change the HTML structure. Adding new elements, removing existing elements, or changing class names requires an SDK code change.

Using Custom CSS with Theme Tokens

customCssUrl can be used together with the existing theme token system:

GatewayEmbeddedSignup.init({
  publishableKey: 'pb_...',

  customCssUrl: '/your-modal-theme.css',
});

In this case:

The SDK loads its default CSS.
The customer CSS file is loaded after the default CSS.
Theme token values are applied as inline custom properties on the Shadow DOM host.

If the same --gw-* variable is provided both in theme and in the CSS file, the theme value wins.

Priority Rules

The final styling depends on what the customer CSS overrides.

Same CSS Variable: Theme Token Wins

theme: {
  primary: '#0B7A4E',
}

:host {
  --gw-primary: red;
}

Result: --gw-primary is #0B7A4E. Reason: theme token values are written as inline custom properties on the Shadow DOM host, so they override :host { --gw-primary: red; } from the stylesheet.

Direct Selector Property: Customer CSS Wins

The SDK default CSS uses the token like this:

.btn--primary {
  background: var(--gw-primary);
}

The customer passes a theme token:

theme: {
  primary: '#0B7A4E',
}

But the customer CSS file sets the button background directly:

.btn--primary {
  background: purple;
}

Result: the .btn--primary background is purple. Reason: the customer stylesheet directly overrides the SDK default background: var(--gw-primary) declaration. Short rule:

theme token vs. --gw-* variable in the CSS file: the theme token wins.
theme token vs. direct selector property in the CSS file: the customer CSS file wins.

Partial CSS Is Supported

Customers do not need to rewrite the whole modal stylesheet. They can provide only the selectors and properties they want to change.

.modal {
  max-width: 840px;
}

.btn--primary {
  border-radius: 2px;
}

Only the modal width and primary button radius change. Everything else continues to come from the theme tokens or SDK default CSS.

Security and URL Rules

Accepted customCssUrl values:

Same-origin relative URL: /your-modal-theme.css
HTTPS absolute URL: https://cdn.customer.example/your-modal-theme.css
Loopback HTTP for local development: http://localhost:3000/your-modal-theme.css

Rejected examples:

customCssUrl: 'javascript:alert(1)'
customCssUrl: 'data:text/css,*{display:none}'
customCssUrl: 'http://cdn.customer.example/theme.css'
customCssUrl: 'https://cdn.customer.example/theme.css#section'
customCssUrl: 'https://user:pass@cdn.customer.example/theme.css'

Invalid values do not break onboarding. The SDK ignores the stylesheet, logs a console warning, and emits a config_warning event through onEvent.

Custom CSS CSP Note

If the customer application uses Content Security Policy, allow inline SDK styles and the custom stylesheet origin:

style-src 'self' 'unsafe-inline';

For a same-origin CSS file, 'self' is enough. If the CSS file is hosted on another CDN origin, add that origin to style-src:

style-src 'self' 'unsafe-inline' https://cdn.customer.example;

The SDK injects its default CSS into the Shadow DOM as an inline <style>, so 'unsafe-inline' is required when a CSP is present. This section only covers CSP requirements for modal styling. For the complete Meta popup, relay iframe, script, and API policy, see Browser Security Headers.

Getting Started

Guides

Visual Customisation Theme

Logo

Custom CSS URL

Usage

How It Works

Example CSS

Supported Styling Selectors

CSS Changes Appearance, Not HTML Structure

Using Custom CSS with Theme Tokens

Priority Rules

Same CSS Variable: Theme Token Wins

Direct Selector Property: Customer CSS Wins

Partial CSS Is Supported

Security and URL Rules

Custom CSS CSP Note

​Visual Customisation Theme

​Logo

​Custom CSS URL

​Usage

​How It Works

​Example CSS

​Supported Styling Selectors

​Connection Type Modal Selectors

​Meta Login Wait and Processing Selectors

​CSS Changes Appearance, Not HTML Structure

​Using Custom CSS with Theme Tokens

​Priority Rules

​Same CSS Variable: Theme Token Wins

​Direct Selector Property: Customer CSS Wins

​Partial CSS Is Supported

​Security and URL Rules

​Custom CSS CSP Note

Visual Customisation Theme

Logo

Custom CSS URL

Usage

How It Works

Example CSS

Supported Styling Selectors

Connection Type Modal Selectors

Meta Login Wait and Processing Selectors

CSS Changes Appearance, Not HTML Structure

Using Custom CSS with Theme Tokens

Priority Rules

Same CSS Variable: Theme Token Wins

Direct Selector Property: Customer CSS Wins

Partial CSS Is Supported

Security and URL Rules

Custom CSS CSP Note