JavaScript SDK

The OpnForm JavaScript SDK enables you to programmatically control embedded forms, listen to events, and build dynamic integrations. It includes automatic iframe resizing and full backward compatibility with existing embeds.

Installation

Include the SDK script after your form iframe:

<iframe
    id="my-form"
    src="https://opnform.com/forms/my-form-slug"
    style="border:none;width:100%;"
></iframe>
<script src="https://opnform.com/widgets/opnform-sdk.min.js"></script>

The SDK automatically discovers OpnForm iframes on your page and initializes them. No additional setup required.

Automatic campaign attribution

The SDK automatically captures supported campaign parameters from the parent page and stores them with the submission under meta.attribution. Parameters already present in the iframe src take precedence over values from the parent page. Supported campaign parameters are utm_source, utm_medium, utm_campaign, utm_id, utm_term, utm_content, utm_source_platform, utm_creative_format, utm_marketing_tactic, gclid, gbraid, wbraid, dclid, fbclid, ttclid, and msclkid. Only these parameters are transmitted to the form. Other URL parameters and the complete parent URL are not captured. A raw cross-origin iframe without the SDK can only capture parameters included directly in its own src.

Quick Start

// Listen to form submission
opnform.on("submit", function (data) {
    console.log("Form submitted!", data);
    console.log("Submission data:", data.data);
});

// Set a field value
opnform.get("my-form").setField("email", "user@example.com");

// Toggle dark mode
opnform.get("my-form").toggleDarkMode();

Events

Listen to form events to trigger custom actions, send data to analytics, or integrate with your application.

Available Events

Event	Description	Payload
`ready`	Form iframe loaded and ready	`{ form, slug, id }`
`submit`	Form submitted successfully	`{ form, data, submissionId, completionTime, meta? }`
`submitStart`	Submission started	`{ form }`
`submitError`	Submission failed	`{ form, errors }`
`dataChange`	Form data changed	`{ form, data, changedField, previousValue, newValue }`
`error`	Validation error occurred	`{ form, errors }`
`pageChange`	Page navigation (multi-page forms)	`{ form, fromPage, toPage, totalPages }`
`nextPage`	User proceeded to next page	`{ form, currentPage, totalPages }`
`previousPage`	User went back	`{ form, currentPage, totalPages }`
`reset`	Form was reset	`{ form }`
`show`	Popup form opened	`{ form }`
`hide`	Popup form closed	`{ form }`

Listening to Events

opnform.on('submit', function(data) {
  console.log('Form submitted:', data);
  console.log('Campaign attribution:', data.meta?.attribution);
});

opnform.on(["nextPage", "previousPage"], function (data) {
    console.log("Page changed to:", data.currentPage);
});

opnform.get("contact-form").on("submit", function (data) {
    console.log("Contact form submitted");
});

opnform.once("ready", function (data) {
    console.log("Form is ready");
});

Removing Event Listeners

// Remove specific handler
const handler = (data) => console.log(data);
opnform.on("submit", handler);
opnform.off("submit", handler);

// Remove all listeners for an event
opnform.off("submit");

Form Methods

Access form instances using opnform.get('form-slug') and call methods to control the form.

Field Operations

setField(fieldId, value)

Set the value of a specific field.

opnform.get("my-form").setField("email", "user@example.com");
opnform.get("my-form").setField("name", "John Doe");

// Works for hidden fields too
opnform.get("my-form").setField("utm_source", "google");

setFields(data)

Set multiple field values at once.

opnform.get("my-form").setFields({
    name: "John Doe",
    email: "john@example.com",
    company: "Acme Inc",
    utm_source: "landing_page",
});

getField(fieldId)

Get the current value of a field.

const email = opnform.get("my-form").getField("email");
console.log(email); // "user@example.com"

getData()

Get all current form data.

const formData = opnform.get("my-form").getData();
console.log(formData);
// { name: "John", email: "john@example.com", ... }

clearField(fieldId) / clearAll()

Clear field values.

// Clear single field
opnform.get("my-form").clearField("email");

// Clear all fields
opnform.get("my-form").clearAll();

Error Handling

// Check if a field has an error
const hasError = opnform.get("my-form").hasError("email");

// Get error message for a field
const errorMsg = opnform.get("my-form").getError("email");

// Get all errors
const errors = opnform.get("my-form").getErrors();
// { email: "Invalid email format", phone: "Required" }

Theme Control

// Toggle dark mode
opnform.get("my-form").toggleDarkMode();

// Set specific mode
opnform.get("my-form").setDarkMode(true); // Dark
opnform.get("my-form").setDarkMode(false); // Light
opnform.get("my-form").setDarkMode("auto"); // Follow system

// Check current mode
const isDark = opnform.get("my-form").isDarkMode();

// Navigate to specific page
opnform.get("my-form").goToPage(2);

// Navigate forward/backward
opnform.get("my-form").nextPage();
opnform.get("my-form").previousPage();

// Get current page info
const page = opnform.get("my-form").getCurrentPage();
// { index: 1, total: 4 }

// Check navigation availability
const canNext = opnform.get("my-form").canGoNext();
const canPrev = opnform.get("my-form").canGoPrevious();

Form Actions

// Submit form programmatically
opnform.get("my-form").submit();

// Reset form to initial state
opnform.get("my-form").reset();

// Focus on first error field
opnform.get("my-form").focusFirstError();

For forms embedded as popups:

// Open popup
opnform.get("my-form").open();

// Close popup
opnform.get("my-form").close();

// Toggle popup
opnform.get("my-form").toggle();

// Check if open
const isOpen = opnform.get("my-form").isOpen();

Global SDK Methods

Form Management

// Get a specific form instance
const form = opnform.get("my-form-slug");

// Get all forms on the page
const forms = opnform.getAll();

// Check if a form is ready
const isReady = opnform.isReady("my-form-slug");

Initialization Options

opnform.init({
    autoResize: true, // Auto-resize iframes (default: true)
    defaultDarkMode: "auto", // 'auto' | true | false
    preventRedirect: false, // Prevent redirect after submission
    onReady: function (forms) {
        // Callback when all forms ready
        console.log("All forms ready:", forms);
    },
});

Programmatic Form Creation

Use opnform.create(slugOrUrl, options) to create an iframe for an existing form. Pass either its slug or its full share URL. With a slug, the iframe loads from https://opnform.com by default, regardless of your page’s domain or where you load the SDK script.

opnform.create("my-form-slug", {
    container: "#form-container", // CSS selector or element
    width: "100%",
    height: "auto",
    darkMode: false,
    onSubmit: function (data) {
        console.log("Submitted:", data);
    },
});

If you have the form’s share URL, pass it directly. This works with OpnForm Cloud, custom domains, subdomains, and self-hosted instances:

opnform.create("https://forms.example.com/forms/my-form-slug?email=user%40example.com", {
    container: "#form-container",
});

The URL must use http:// or https:// and point to a public form at /forms/{slug}. Its query parameters and fragment are preserved. You can access the resulting form with opnform.get("my-form-slug") as usual. If you only have the slug, pass baseUrl to select a custom domain or a self-hosted instance. Include the protocol:

opnform.create("my-form-slug", {
    container: "#form-container",
    baseUrl: "https://forms.example.com",
});

This loads https://forms.example.com/forms/my-form-slug inside the iframe.

A full URL takes precedence over baseUrl; its host is never replaced.
With a slug, baseUrl defaults to https://opnform.com. The SDK does not look up the form’s custom domain automatically.
An explicit darkMode option overrides the value in the URL. The SDK sets its own _sdkToken and _sdkParentOrigin parameters for iframe communication.
Existing iframes keep their own src.

If your integration previously relied on create() loading from the page’s domain, pass that instance’s baseUrl explicitly or use the full share URL.

Integration Examples

Google Analytics 4

opnform.on("submit", function (data) {
    gtag("event", "form_submission", {
        form_id: data.form.id,
        form_name: data.form.slug,
        completion_time: data.completionTime,
    });
});

opnform.on("pageChange", function (data) {
    gtag("event", "form_progress", {
        form_id: data.form.id,
        current_page: data.toPage,
        total_pages: data.totalPages,
    });
});

Send to Custom API

opnform.on("submit", async function (data) {
    await fetch("/api/leads", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
            email: data.data.email,
            name: data.data.name,
            source: "opnform",
            formId: data.form.id,
        }),
    });
});

Error Tracking

opnform.on("submitError", function (data) {
    console.error("Form submission failed:", data.errors);

    // Send to error tracking service
    Sentry.captureMessage("Form submission failed", {
        extra: { formId: data.form.id, errors: data.errors },
    });
});

opnform.on("error", function (data) {
    console.log("Validation errors:", data.errors);
});

Dynamic Field Population

opnform.once("ready", function () {
    // Get data from URL params
    const params = new URLSearchParams(window.location.search);

    opnform.get("my-form").setFields({
        email: params.get("email") || "",
        utm_source: params.get("utm_source") || "direct",
        utm_campaign: params.get("utm_campaign") || "",
    });
});

Custom Code Integration

The SDK is automatically available when using the Custom Code feature in OpnForm. You can add custom JavaScript directly in your form or workspace settings, and the window.opnform SDK will be ready to use.

Custom Code works without iframes - the SDK is initialized directly on your form page, giving you full access to form methods and events.

Adding Custom Code

Go to your form’s Settings → Custom Code (or Workspace Settings for workspace-wide code)
Add your JavaScript code in a <script> tag
The SDK (window.opnform) is automatically available

Example: Google Analytics Tracking

<script>
    // Track form submission
    opnform.on("submit", function (data) {
        gtag("event", "form_submission", {
            form_slug: data.form.slug,
            submission_id: data.submissionId,
        });
    });

    // Track page progress
    opnform.on("pageChange", function (data) {
        gtag("event", "form_progress", {
            page: data.toPage + 1,
            total_pages: data.totalPages,
        });
    });
</script>

Example: Facebook Pixel

<script>
    opnform.on("submit", function (data) {
        fbq("track", "Lead", {
            content_name: data.form.slug,
        });
    });
</script>

Example: Conditional Logic with External Data

<script>
    opnform.once("ready", function () {
        // Fetch user data and pre-fill form
        fetch("/api/user-info")
            .then((r) => r.json())
            .then((user) => {
                opnform.get("my-form").setFields({
                    email: user.email,
                    name: user.name,
                });
            });
    });
</script>

Example: Custom Validation Feedback

<script>
    opnform.on("error", function (data) {
        // Show custom toast notification for errors
        Object.values(data.errors).forEach(function (error) {
            showToast(error, "error");
        });
    });

    opnform.on("submit", function (data) {
        showToast("Thank you for your submission!", "success");
    });
</script>

Example: Live Data Change Tracking

<script>
    opnform.on("dataChange", function (data) {
        console.log("Field changed:", data.changedField);
        console.log("New value:", data.newValue);

        // Example: Show/hide elements based on form data
        if (data.changedField === "country" && data.newValue === "US") {
            document.querySelector(".us-only-info").style.display = "block";
        }
    });
</script>

Accessing Form Data Directly

<script>
    opnform.once("ready", function () {
        var form = opnform.get("my-form-slug");

        // Get all current form data
        var data = form.getData();
        console.log("Current form data:", data);

        // Get specific field value
        var email = form.getField("email");

        // Check if field has validation error
        if (form.hasError("email")) {
            console.log("Email error:", form.getError("email"));
        }

        // Get current page (for multi-page forms)
        var page = form.getCurrentPage();
        console.log("Page " + (page.index + 1) + " of " + page.total);
    });
</script>

Backward Compatibility

Existing embeds using initEmbed() continue to work without changes. The SDK provides full backward compatibility.

<!-- Old embed code still works -->
<iframe id="my-form" src="https://opnform.com/forms/my-form"></iframe>
<script src="https://opnform.com/widgets/iframe.min.js"></script>
<script>
    initEmbed("my-form", { autoResize: true });
</script>

We recommend upgrading to the new SDK to access event callbacks and programmatic control features.

Troubleshooting

Form not found

Ensure the iframe has loaded and the id attribute matches the form slug:

<iframe id="my-form-slug" src="https://opnform.com/forms/my-form-slug"></iframe>

Use opnform.getAll() to see discovered forms.

Events not firing

Make sure the SDK script is loaded after the iframe:

<iframe ...></iframe>
<script src="https://opnform.com/widgets/opnform-sdk.min.js"></script>
<script>
    // Your event handlers here
</script>

Commands not working

Commands require the form to be ready. Use the ready event:

opnform.once("ready", function () {
    opnform.get("my-form").setField("email", "test@example.com");
});

Auto-resize not working

The SDK includes iFrame Resizer. If resize isn’t working, ensure:

No CSS max-height restricting the iframe
The form is not in focused presentation style (which has fixed height)

Get Started

Features

Deployment

Self-hosted Enterprise

Configuration

Embedding

Integrations

Installation

Automatic campaign attribution

Quick Start

Events

Available Events

Listening to Events

Removing Event Listeners

Form Methods

Field Operations

Error Handling

Theme Control

Navigation (Multi-Page Forms)

Form Actions

Global SDK Methods

Form Management

Initialization Options

Programmatic Form Creation

Integration Examples

Google Analytics 4

Send to Custom API

Error Tracking

Dynamic Field Population

Custom Code Integration

Adding Custom Code

Example: Google Analytics Tracking

Example: Facebook Pixel

Example: Conditional Logic with External Data

Example: Custom Validation Feedback

Example: Live Data Change Tracking

Accessing Form Data Directly

Backward Compatibility

Troubleshooting

​Installation

​Automatic campaign attribution

​Quick Start

​Events

​Available Events

​Listening to Events

​Removing Event Listeners

​Form Methods

​Field Operations

​Error Handling

​Theme Control

​Navigation (Multi-Page Forms)

​Form Actions

​Popup Control

​Global SDK Methods

​Form Management

​Initialization Options

​Programmatic Form Creation

​Integration Examples

​Google Analytics 4

​Send to Custom API

​Error Tracking

​Dynamic Field Population

​Custom Code Integration

​Adding Custom Code

​Example: Google Analytics Tracking

​Example: Facebook Pixel

​Example: Conditional Logic with External Data

​Example: Custom Validation Feedback

​Example: Live Data Change Tracking

​Accessing Form Data Directly

​Backward Compatibility

​Troubleshooting

Installation

Automatic campaign attribution

Quick Start

Events

Available Events

Listening to Events

Removing Event Listeners

Form Methods

Field Operations

Error Handling

Theme Control

Navigation (Multi-Page Forms)

Form Actions

Popup Control

Global SDK Methods

Form Management

Initialization Options

Programmatic Form Creation

Integration Examples

Google Analytics 4

Send to Custom API

Error Tracking

Dynamic Field Population

Custom Code Integration

Adding Custom Code

Example: Google Analytics Tracking

Example: Facebook Pixel

Example: Conditional Logic with External Data

Example: Custom Validation Feedback

Example: Live Data Change Tracking

Accessing Form Data Directly

Backward Compatibility

Troubleshooting