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'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 Enhanced Conversions

ProForms natively supports Google Ads conversion tracking with Enhanced Conversions — no GTM required. Add your Google Ads ID and Conversion Label in the Tracking tab, and ProForms handles everything automatically.

How It Works

1. The embed loads gtag.js with allow_enhanced_conversions: true
2. On form submission, it auto-detects email, phone, name, and address fields by field type
3. User data is SHA-256 hashed client-side (via Web Crypto API) before being sent to Google
4. The conversion event fires with hashed user_data attached for improved attribution matching

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",
        "googleAdsEnhancedConversions": true  // opt-in
      }
    }
  }'

What Gets Sent

ProForms maps form field types to Google's user_data schema automatically:

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.

GTM / dataLayer

Even without configuring Google Ads directly in ProForms, every submission pushes a proforms_submission event to the dataLayer with user data fields for GTM-based Enhanced Conversions:

{
  event: "proforms_submission",
  proforms_form_id: "uuid",
  proforms_form_name: "Contact Form",
  proforms_user_email: "user@example.com",      // if email field exists
  proforms_user_phone: "+18015551234",           // if phone field exists
  proforms_user_first_name: "John",              // if name field exists
  proforms_user_last_name: "Doe"
}

Use these dataLayer variables in your GTM Enhanced Conversions tag to pass user data to Google Ads without any custom code.

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, Facebook Pixel, and Google Ads conversion tracking
• Google Ads Enhanced Conversions with automatic field detection and SHA-256 hashing
• 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;
}