JavaScript Embed

The recommended way to embed ProForms on any website. Add a single script tag and the form renders itself — full styling, validation, auto-formatting, and submission handling included. No dependencies, no build step.

Basic Embed

Drop this snippet wherever you want the form to appear:

HTML

<script src="https://proforms.io/embed.js" data-form="YOUR_FORM_UUID"></script>

The script inserts the form immediately after itself. Copy the snippet from your form's Share tab in the builder.

Embed Modes

Control how the form's CSS interacts with your site using data-mode:

HTML

<!-- Isolated (default) — Shadow DOM, fully scoped, no CSS bleed -->
<script src="https://proforms.io/embed.js"
        data-form="YOUR_FORM_UUID"
        data-mode="isolated"></script>

<!-- Open — inherits your site's CSS, useful for tight design integration -->
<script src="https://proforms.io/embed.js"
        data-form="YOUR_FORM_UUID"
        data-mode="open"></script>

Attribute	Values	Description
data-form	string (required)	Your form UUID
data-mode	"isolated" \| "open"	Shadow DOM isolation (default: "isolated")

Caching & Updates

The embed fetches your form config from /api/v1/f/:uuid on every page load. Responses use Cache-Control: no-cache with an ETag based on the form version, so the browser revalidates on every load but only downloads new data when the form has changed (304 Not Modified otherwise).

💡

Changes made via the API or dashboard are reflected on the next page load — no cache purging needed. The form's version number increments on every update and drives cache invalidation automatically.

Multiple Forms on One Page

Add multiple script tags — each renders independently:

HTML

<!-- Contact form -->
<script src="https://proforms.io/embed.js" data-form="FORM_UUID_1"></script>

<!-- Newsletter signup -->
<script src="https://proforms.io/embed.js" data-form="FORM_UUID_2"></script>

reCAPTCHA v3

When settings.security.recaptchaEnabled is true on a form, the embed automatically loads the reCAPTCHA v3 script and attaches a token to every submission. No extra configuration needed.

The embed resolves the reCAPTCHA site key using this priority order:

The site's custom recaptchaSiteKey (if configured via the Sites API or Site Settings)
The ProForms platform global key (fallback — works on any domain)

Server-side verification uses the matching secret key in the same priority order. The score threshold is controlled per-form via settings.security.recaptchaThreshold (default: 0.5).

Badge Display

Google requires either the floating reCAPTCHA badge or a text attribution to be visible. Control this per-form with settings.security.recaptchaBadgeMode:

Value	Behavior
"text"	Default. Hides the floating badge. Shows a centered one-line attribution at the bottom: "Protected by reCAPTCHA · Privacy · Terms"
"badge"	Shows Google's default floating corner badge. No text attribution added.
"none"	Hides both badge and text. You're responsible for adding your own reCAPTCHA attribution.

💡

If you're using the platform global key, make sure domain verification is disabled in your Google reCAPTCHA admin console so the key works on any domain your forms are embedded on.

What the Embed Handles

Field rendering — all field types including file upload
Client-side validation with error messages
Email field format validation (standard, strict, or none)
Phone field auto-formatting and digit-only enforcement
Conditional logic (show/hide fields based on values)
Theme CSS variables from your form settings
Custom CSS injection (scoped to shadow DOM in isolated mode)
reCAPTCHA v3 with hybrid key resolution and honeypot spam protection
Google Analytics and Facebook Pixel tracking events
UTM parameter capture
File upload with progress
Multi-step form navigation
Thank you message or redirect after submission

💡

Use isolated mode (default) for most sites — it prevents CSS conflicts and ensures your form looks exactly as designed. Switch to open mode if you need the form to inherit your site's font family or want to style it entirely with your own CSS.