Content type plugins

Content type plugins let you add new question types to Feedal. Your UI runs in a sandboxed iframe; the host page communicates with it via a postMessage protocol. The @feedal/content-type-sdk package provides a minimal bridge so you don’t have to implement the protocol yourself.

Security model

Community plugin UI never runs in the Feedal origin. Your bundle is loaded in an iframe with sandbox="allow-scripts" only:

No access to the parent page’s DOM, localStorage, or cookies
No cross-origin network requests from the iframe (except to your own CDN for the bundle itself)
postMessage is the only communication channel between your plugin and Feedal

This means respondent data stays in Feedal’s hands — your iframe receives the current answer value and node config, and can only send back an answer value or a size hint.

How it works

Feedal host page
│
├── sends: PLUGIN_RENDER (node, mode, currentValue)
│
└─── iframe (your bundle, sandboxed)
      ├── calls: signalReady()          → parent receives PLUGIN_READY
      ├── calls: sendAnswer(value)      → parent receives PLUGIN_ANSWER
      └── calls: sendSize(height)       → parent receives PLUGIN_SIZE

Installing the SDK

npm install @feedal/content-type-sdk
# or
pnpm add @feedal/content-type-sdk

SDK reference

import { onRender, sendAnswer, signalReady, sendSize } from "@feedal/content-type-sdk";

// Tell Feedal your iframe is ready to receive renders
signalReady();

// Listen for render events (called every time the node is shown or the value changes)
const unsubscribe = onRender((payload) => {
  const { node, mode, value } = payload;
  // node   — the full GraphNode object (id, question_type, data.config, etc.)
  // mode   — "preview" | "interactive" | "readonly"
  // value  — the current answer value (null if unanswered)
  renderMyUI(node, mode, value);
});

// Send the respondent's answer back to Feedal
sendAnswer("the answer value");

// Tell Feedal to resize the iframe (call when your content height changes)
sendSize(350);  // height in pixels

`onRender(callback)`

Registers a callback that fires every time Feedal sends a PLUGIN_RENDER message. Returns an unsubscribe function. The RenderPayload passed to the callback:

Field	Type	Description
`node`	`Record<string, unknown>`	Full node object from the graph
`mode`	`"preview" \| "interactive" \| "readonly"`	Current render context
`value`	`unknown`	Current answer value (`null` if none)

`sendAnswer(value)`

Sends the respondent’s answer to the host page. Call this when the user makes a selection or submits input. value can be any JSON-serialisable type.

`signalReady()`

Signals to the host page that your iframe has finished loading and is ready to receive PLUGIN_RENDER messages. Call this once, after your bundle is initialised.

`sendSize(height)`

Requests the host page to resize the iframe to height pixels. Call this whenever your content changes height to avoid scroll bars or clipped content.

Raw postMessage protocol

If you’re not using the SDK, here are the raw message types: Host → iframe

`type`	Additional fields	Description
`PLUGIN_RENDER`	`node`, `mode`, `value`	Render the question with this data

iframe → host

`type`	Additional fields	Description
`PLUGIN_READY`	—	iframe has initialised
`PLUGIN_ANSWER`	`value`	Respondent submitted an answer
`PLUGIN_SIZE`	`height`	Request iframe resize
`PLUGIN_ERROR`	—	Fatal load failure

Building your bundle

Your renderer must be a self-contained ES module bundle served over HTTPS. The renderer_bundle_url in your manifest must point to this file.

# Example using Vite
vite build --lib --entry src/index.ts --formats es

The bundle is loaded into the iframe as a <script type="module">. There is no HTML shell — your bundle is responsible for creating DOM elements and appending them to document.body.

Minimal example

import { onRender, sendAnswer, signalReady, sendSize } from "@feedal/content-type-sdk";

// Build UI using safe DOM methods (never insert untrusted data via innerHTML)
const container = document.createElement("div");
document.body.appendChild(container);

onRender(({ node, mode, value }) => {
  // Clear previous content safely
  while (container.firstChild) container.removeChild(container.firstChild);

  if (mode === "readonly") {
    const text = document.createElement("span");
    text.textContent = String(value ?? "—");   // textContent is XSS-safe
    container.appendChild(text);
    sendSize(40);
    return;
  }

  const input = document.createElement("input");
  input.type = "text";
  input.value = String(value ?? "");
  input.placeholder = String(node?.data?.config?.placeholder ?? "Enter value");

  input.addEventListener("change", () => {
    sendAnswer(input.value);
  });

  container.appendChild(input);
  sendSize(60);
});

signalReady();

Validation

What the framework handles

Feedal enforces one rule on behalf of every question type, including plugins: required fields. If node.data.is_required is true and the respondent hasn’t submitted an answer yet, the runner blocks navigation and shows “This field is required.” before your plugin ever receives a PLUGIN_RENDER event for the next node. That’s the only validation the framework performs for plugins. Everything else is your responsibility.

What your plugin handles

All content-level validation — format checks, range limits, minimum selections, custom business rules — must be enforced inside the iframe. The pattern is:

Show the input and let the respondent interact.
When input is invalid, display an inline error message inside the iframe and do not call sendAnswer().
Only call sendAnswer(value) once the value is valid.

Because the runner only advances when it receives a PLUGIN_ANSWER message, withholding sendAnswer() is the complete and correct way to block navigation. There is no separate validation API.

// Example: only send a valid answer
input.addEventListener("change", () => {
  const raw = input.value.trim();
  if (raw.length < 3) {
    errorEl.textContent = "Please enter at least 3 characters.";
    return; // do NOT call sendAnswer — navigation stays blocked
  }
  errorEl.textContent = "";
  sendAnswer(raw);
});

The `needsContinueButton` manifest field

By default, plugins behave like choice or rating questions: the runner expects sendAnswer() to be called on a single user action and does not render an explicit Continue button. If your plugin has a multi-step input or needs the respondent to explicitly confirm before advancing (for example, a signature pad or a file picker with a preview step), set needs_continue_button: true in your manifest:

{
  "type": "content_type",
  "question_type_id": "signature-capture",
  "display_name": "Signature Capture",
  "renderer_bundle_url": "https://cdn.example.com/signature-plugin/v1.0.0/bundle.esm.js",
  "version": "1.0.0",
  "icon": "✍️",
  "needs_continue_button": true
}

When needs_continue_button is true, Feedal renders a themed Continue button below your iframe — the same button used for text input questions. The respondent clicks it to advance; your plugin should already have called sendAnswer() with the current value before that click. If needs_continue_button is false (the default), no Continue button is rendered. Your plugin should call sendAnswer() as the final confirmation action.

`answerSchema`

The answerSchema field in the manifest is informational only. It documents the shape of the value you pass to sendAnswer() and is used for type hints in the developer portal and the Results Hub. Feedal does not validate answer values against this schema at runtime.

Registering with the manifest

Add a content_type extension point to your app manifest:

{
  "type": "content_type",
  "question_type_id": "signature-capture",
  "display_name": "Signature Capture",
  "renderer_bundle_url": "https://cdn.example.com/signature-plugin/v1.0.0/bundle.esm.js",
  "version": "1.0.0",
  "icon": "✍️"
}

Once your app is approved in the marketplace, the question_type_id becomes available in the studio’s Add content panel and in the form graph as "question_type": "plugin:signature-capture".

Testing locally

During development, simulate the postMessage protocol in a plain HTML file to test your bundle without a live Feedal account:

<!DOCTYPE html>
<html>
<body>
  <iframe id="plugin" sandbox="allow-scripts"></iframe>
  <script type="module">
    const frame = document.getElementById("plugin");

    window.addEventListener("message", (e) => {
      if (e.data.type === "PLUGIN_READY") {
        frame.contentWindow.postMessage({
          type: "PLUGIN_RENDER",
          node: { id: "test", data: { config: {} } },
          mode: "interactive",
          value: null,
        }, "*");
      }
      if (e.data.type === "PLUGIN_ANSWER") {
        console.log("Answer received:", e.data.value);
      }
    });
  </script>
</body>
</html>

Point the iframe src to a local server that serves your bundle.

Next steps

Developer portal

Submit your plugin for marketplace review.

Marketplace

Browse community and official plugins.

REST API

Developer Portal

Content type plugins

Security model

How it works

Installing the SDK

SDK reference

`onRender(callback)`

`sendAnswer(value)`

`signalReady()`

`sendSize(height)`

Raw postMessage protocol

Building your bundle

Minimal example

Validation

What the framework handles

What your plugin handles

The `needsContinueButton` manifest field

`answerSchema`

Registering with the manifest

Testing locally

Next steps

Developer portal

Marketplace

​Security model

​How it works

​Installing the SDK

​SDK reference

​onRender(callback)

​sendAnswer(value)

​signalReady()

​sendSize(height)

​Raw postMessage protocol

​Building your bundle

​Minimal example

​Validation

​What the framework handles

​What your plugin handles

​The needsContinueButton manifest field

​answerSchema

​Registering with the manifest

​Testing locally

​Next steps

Developer portal

Marketplace

Security model

How it works

Installing the SDK

SDK reference

`onRender(callback)`

`sendAnswer(value)`

`signalReady()`

`sendSize(height)`

Raw postMessage protocol

Building your bundle

Minimal example

Validation

What the framework handles

What your plugin handles

The `needsContinueButton` manifest field

`answerSchema`

Registering with the manifest

Testing locally

Next steps