Embed a form

Snippet builder

Choose how the form appears and the code updates for each kind of website. In OneForm, the same code is under a form's Share tab, with your form's slug and colours already in. Only published forms load for visitors.

<div data-oneform="your-form" data-of-type="inline" style="width:100%"></div><script src="https://app.oneform.si/embed.js" async></script>

Embed types

Voice forms offer floating orb, inline card, button → popup, full page. A conversation always opens in a popup, never a slider.

Data attributes

Everything is set with attributes on the element; the loader at https://app.oneform.si/embed.js reads them. Load the script once per page, however many forms the page has.

A popup or slider element with content of its own (a button or link inside it, say) opens the form when clicked, so your own markup can be the trigger.

JavaScript API

The loader adds window.OneForm. It runs once however often the script is included, and Escape closes an open form.

// After /embed.js has loaded:window.OneForm.open("your-form"); // open a popup, slider, chat bubble or side tab by its slugwindow.OneForm.close(); // close whatever is openwindow.OneForm.scan(); // look for new <div data-oneform> elements (single-page apps) window.OneForm.on("submitted", (e) => {  // e.slug, e.endingId. Never the answers.  console.log("Submitted", e.slug);});

In single-page apps (React, Vue, Next.js and the like), call window.OneForm.scan() after the element mounts; the framework snippets above do this for you.

Events

The form tells the page what happens through postMessage. The loader passes each message on to window.OneForm.on listeners and fires it on the element as a oneform:<type> DOM event. Messages never contain answers.

document.querySelector("[data-oneform]").addEventListener("oneform:submitted", (e) => {  console.log(e.detail); // the same data as window.OneForm.on});

Every message has the shape { source: "oneform", v: 1, id, type, ...data }, where id tells several embeds on one page apart. The loader only accepts messages from the OneForm origin and the frame it made. In the other direction, it sends pause (the panel was closed: a voice conversation stops talking and listening).

Hidden fields and UTM tags

• A form declares its hidden fields (a client id, a referrer). Only declared keys and the five UTM tags (utm_source, utm_medium, utm_campaign, utm_term, utm_content) are kept; anything else is dropped, and each value is cut to 300 characters.
• UTM tags in the page's address always pass through to the form.
• data-of-hidden="client_id,ref" passes those page parameters through too, so ?client_id=TD-1042 on your page reaches the form.
• data-of-hidden-values="source=pricing;plan=pro" sets fixed values for that embed.
• Links work the same way: https://app.oneform.si/f/your-form?client_id=TD-1042. The API can make prefilled links for you.

Hidden values arrive with the submission and in webhook payloads under hidden.

Content-Security-Policy

If your site sets a Content-Security-Policy, add these sources to the matching directives you already have:

script-src https://app.oneform.si;frame-src https://app.oneform.si;style-src 'unsafe-inline';connect-src https://app.oneform.si;

• script-src and frame-src: the script, and the form's frame.
• style-src 'unsafe-inline': the script adds one small <style> element for popups, sliders and launchers, and the inline snippet sizes its element with a style attribute. A nonce or hash can't match the added styles, so it needs 'unsafe-inline'.
• connect-src: only for voice forms. The orb fetches its colours from the OneForm origin; if that's blocked, it keeps the colours in its snippet.

With a nonce-based policy, give the script tag your nonce. Voice forms need the microphone: the frame asks for it with allow="microphone", so a Permissions-Policy on your page must not block it.

Without JavaScript

Where scripts aren't allowed, use a plain iframe. It has a fixed height and no popups, events or page parameters.

<iframe src="https://app.oneform.si/f/your-form?embed=iframe" width="100%" height="640" style="border:0;border-radius:12px" allow="microphone; autoplay; clipboard-write" title="Form"></iframe>