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:

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

<!-- 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&apos;s CSS, useful for tight design integration -->
<script src="https://proforms.io/embed.js"
        data-form="YOUR_FORM_UUID"
        data-mode="open"></script>

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).

Multiple Forms on One Page

Add multiple script tags — each renders independently:

<!-- 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:

1. The site's custom recaptchaSiteKey (if configured via the Sites API or Site Settings)
2. 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:

Google Ads Tracking

ProForms keeps tracking simple with two site modes: Enhanced + Tag for browser-side conversions after successful submit, and Disabled for offline-feed-only or client-owned thank-you page tracking.

How It Works

1. Enhanced + Tag: the embed loads configured tags and fires Google Ads conversion tracking only after successful submit.
2. If Enhanced Conversions are enabled, ProForms hashes supported user fields and sends them with the conversion event.
3. The Google Ads conversion event includes a transaction ID from the submission so browser and offline paths can be reconciled.
4. Disabled: the embed does not load pixels or emit browser tracking. Use the offline conversion feed or a client-owned thank-you page snippet.

Setup via API

curl -X PUT https://proforms.io/api/v1/forms/:id \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "tracking": {
        "googleAdsId": "AW-123456789",
        "googleAdsConversionLabel": "AbCdEfGhIjKlMn"
      }
    }
  }'

Enhanced + Tag Enhanced Conversions

Enhanced + Tag mode maps form field types to Google's user_data schema when enhanced conversions are enabled:

Compatible Field Types

Enhanced Conversions detection is based on the field typeyou choose in the form builder — not the field label, key, or ID. Renaming a field's key or label has no effect on detection. As long as the field type is one of the four above, it works.

Important Notes

• Privacy-first: All PII (email, phone, name) is SHA-256 hashed in the browser before being sent to Google. Raw values are never transmitted to Google's servers.
• Minimum data: At least one email or phone field is required for enhanced matching. If neither exists, a standard conversion fires instead.
• Multiple fields: If your form has multiple email or phone fields, the last one in the form is used.
• Hidden fields: Fields hidden by conditional logic at the time of submission are excluded.
• Google Ads requirements: You must enable Enhanced Conversions in your Google Ads account (Settings → Conversions → Enhanced Conversions) for the data to be used.
• Both IDs required: You need both the Google Ads ID (AW-XXXXXXXXX) and the Conversion Label from your conversion action. Without the label, no conversion event fires.

dataLayer / Custom Event

In Enhanced + Tag mode, ProForms also pushes a clean proforms_submission_success event after successful submission for additional analytics/GTM workflows:

{
  event: "proforms_submission_success",
  proforms_form_id: "uuid",
  proforms_form_name: "Contact Form",
  proforms_site_name: "Client Site",
  proforms_reference_id: "ABC-123",
  proforms_submission_id: "sub_123"
}

Create a GTM Custom Event trigger for proforms_submission_success if you need additional site-owned analytics or non-primary tracking.

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
• Enhanced + Tag success events for analytics/GTM workflows
• Google Analytics, Facebook Pixel, and Google Ads tracking only in Enhanced + Tag mode
• UTM parameter capture
• File upload with progress
• Multi-step form navigation
• Thank you message or redirect after submission

CSS Class Reference

Target these classes in your customCss to style form elements. Short .pf-* aliases are recommended. Legacy .proform-* names also work.

Structure & Layout

Field Width Modifiers

Applied alongside .pf-field to control column span in the 6-column grid. On screens ≤480px, all fields collapse to full width.

Form Fields

Choice Fields

Compound Fields

Content & UI

State Classes

CSS Variables

These CSS custom properties are set automatically from your form's theme settings. Override them in customCss for full control.

Layout: Side-by-Side Fields

The form body (.pf-body) is a CSS Grid with 6 columns. Fields set to "Half Width" in the builder get .pf-width-half (span 3), creating side-by-side layouts. The gap between all fields — including between side-by-side columns — is controlled by --pf-field-spacing.

/* Adjust spacing between all fields */
.pf-body {
  gap: 24px;
}

/* Style inputs */
.pf-input, .pf-textarea, .pf-select {
  border-radius: 12px;
}

/* Style the submit button */
.pf-submit {
  background: #1a1a1a;
  border-radius: 12px;
}

/* Uppercase labels */
.pf-label {
  font-weight: 500;
  text-transform: uppercase;
  font-size: 11px;
  letter-spacing: 0.05em;
}

/* Override CSS variables */
.pf-form {
  --pf-field-spacing: 24px;
  --pf-radius: 12px;
  --pf-btn-color: #1a1a1a;
}