Embed a survey with your brand

The embed surface renders a survey inside your own site through an iframe, styled with your brand colors instead of the Pollarix default. This guide walks you through embedding a survey and passing a tenant theme through the theme URL parameter. You need a Web Link collector ID from your dashboard (Survey → Collectors → Web Link).

Enable embedding on the collector

Embedding is off by default for every collector. Before the embed URL works, enable Allow embedding on external sites in the collector's settings (Survey → Collectors → Web Link → Response Tracking). A collector that hasn't opted in shows "This survey isn't available for embedding" instead of the survey when framed — this protects surveys that were only ever meant to be shared as a direct link from being framed by third-party sites.

Embed the survey

To embed a survey, point an iframe at the embed URL with your collector ID:

<iframe
  src="https://survey.pollarix.com/embed/YOUR_COLLECTOR_ID"
  title="Customer feedback survey"
  width="100%"
  height="700"
  style="border: 0;"
></iframe>

Without a theme parameter the survey renders in the Pollarix Spectrum default theme — the same look respondents get on a direct survey link.

info

Only the /embed/ path can be framed by other sites. The regular /survey/ and /collector/ pages send X-Frame-Options: DENY and refuse to load inside an iframe. Embedding requires an https: parent page.

Apply your brand

To apply your brand, pass a theme object in the theme query parameter. The theme uses the same JSON shape the survey theme editor produces — themeName, colorPalette, and a cssVariables map:

{
  "themeName": "acme-blue",
  "colorPalette": "light",
  "cssVariables": {
    "--p-color-brand-default": "#1d4ed8",
    "--p-color-fg-on-brand": "#ffffff"
  }
}

Encode it either way:

base64url (recommended)

base64url survives HTML attribute quoting and URL copying:

const theme = {
  themeName: 'acme-blue',
  colorPalette: 'light',
  cssVariables: {
    '--p-color-brand-default': '#1d4ed8',
    '--p-color-fg-on-brand': '#ffffff',
  },
};

const param = btoa(JSON.stringify(theme))
  .replace(/\+/g, '-')
  .replace(/\//g, '_')
  .replace(/=+$/, '');

const src = `https://survey.pollarix.com/embed/YOUR_COLLECTOR_ID?theme=${param}`;

URI-encoded JSON

Readable in the address bar, useful while iterating:

const src =
  'https://survey.pollarix.com/embed/YOUR_COLLECTOR_ID?theme=' +
  encodeURIComponent(JSON.stringify(theme));

Setting --p-color-brand-default alone restyles the whole surface: buttons, selected answers, rating highlights, and hover/pressed states are derived from your brand color automatically. Override the derived tokens explicitly only when you need exact control.

Overridable tokens

The cssVariables map accepts three groups of keys. Anything outside them is ignored (a console warning lists dropped entries) — the survey still renders.

Brand and accent colors

Token	Controls
--p-color-brand-default	Primary brand color — buttons, selection states (derives hover, pressed, and soft tints)
--p-color-brand-hover / --p-color-brand-strong / --p-color-brand-soft / --p-color-brand-text / --p-color-brand-edge	Explicit control over the derived brand shades
--p-color-fg-on-brand	Text on brand-colored surfaces (button labels)
--p-color-cta-default / --p-color-cta-hover / --p-color-cta-soft / --p-color-fg-on-cta	Call-to-action accent (-default derives hover and soft unless you set them)
--p-color-focus-ring-default	Keyboard focus indicator

Surfaces, text, and borders

Token	Controls
--p-color-bg-default / --p-color-bg-canvas	Page background
--p-color-bg-card / --p-color-bg-raised / --p-color-bg-subtle	Question cards and inputs
--p-color-fg-default / --p-color-fg-muted / --p-color-fg-subtle	Question titles, descriptions, helper text
--p-color-border-default / --p-color-border-subtle	Input and card borders
--p-radius-sm / --p-radius-md / --p-radius-lg	Corner rounding (px, rem, em, or % values)

SurveyJS chrome (advanced)

Keys starting with --sjs- pass straight to the SurveyJS theme layer — the same variables a saved survey theme uses (for example --sjs-corner-radius, --sjs-font-surveytitle-weight). Use these for fine-tuning beyond the Pollarix token set.

tip

Color values accept hex, rgb(), hsl(), oklch(), and color-mix(). Values containing url(, var(, or other non-color constructs are rejected.

Check contrast

Pollarix checks your overrides against WCAG 2.x contrast requirements (1.4.3 text contrast, 1.4.11 non-text contrast) when the embed loads. A failing combination — say, white text on a light-yellow brand — still applies, but logs a warning so an unreadable brand never ships silently:

[embed] tenant theme breaks WCAG contrast: --p-color-fg-on-brand (#ffffff)
on --p-color-brand-default (#ffe14d) is 1.29:1 — WCAG 1.4.3 requires 4.5:1

warning

Error: [embed] tenant theme ignored — falling back to the Spectrum default

Cause: The theme parameter isn't valid JSON (or base64url of JSON), or none of its cssVariables keys are overridable.

Fix: Re-encode the payload and confirm the keys against the tables above. The console warning lists each dropped entry with the reason.

Theme precedence

When several theme sources apply to the same survey, later layers win:

1. Spectrum default — the base Pollarix theme.
2. Saved survey theme — applied if the survey has one attached in the dashboard.
3. Your theme parameter — embed overrides sit on top of both.

A survey with no saved theme and no theme parameter renders the Spectrum default.

Next steps

📤

Distribute surveys

Create the Web Link collector the embed uses

🧩

Widget SDK

Pop-over NPS surveys instead of an inline embed

🎨

Build surveys

Design the survey and its saved theme