JavaScript SDK

Programmatically interact with embedded OpnForm forms using our 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", "[e-mail]");

// 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

Single Event

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

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", "[e-mail]");
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: "[e-mail]",
    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); // "[e-mail]"

getData()

Get all current form data.

const formData = opnform.get("my-form").getData();
console.log(formData);
// { name: "John", email: "[e-mail]", ... }

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();

Navigation (Multi-Page Forms)

// 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();

Popup Control

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

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);
    },
});

---

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

1. Go to your form’s Settings → Custom Code (or Workspace Settings for workspace-wide code)
2. Add your JavaScript code in a <script> tag
3. 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", "[e-mail]");
});

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)