Popups

Key Features

• Display Gravity Forms in popups, slide-ins, banners, and fullscreen overlays (configurable display modes)
• Multiple trigger types:
• Button click (CSS selector)
• Exit intent
• Timeout (delay in seconds or milliseconds)
• Scroll depth (percent or pixels)
• URL hash
• JavaScript API (window.GFPopups.show(feedId))
• Targeting rules (configured in the Popups feed settings UI)
• Dismissal + behavior controls:
• close on backdrop click / ESC
• show/hide close button
• optional auto-close after form submission
• cookie-based dismissal (“don’t show again”) controls
• Theme template override support for popup iframe rendering (via gravityformspopups/ templates in your theme)
• Custom iframe template processing supports:
• {form} placeholder
• Gravity Forms merge tags
• conditional template shortcodes: [hide_if_submitted]...[/hide_if_submitted] and [show_if_submitted]...[/show_if_submitted]

Requirements

• WordPress 6.0+ (plugin header)
• PHP 8.0+ (plugin header)
• Gravity Forms 2.8+ (minimum requirement in add-on class)

Installation

1. Upload the gravityformspopups plugin folder to /wp-content/plugins/ (or install via Plugins → Add New → Upload Plugin).
2. Activate Gravity Forms Popups from the WordPress Plugins screen.
3. In WordPress, go to Forms → Popups and:

• Create a popup feed
• Select the Form to Display
• Configure Trigger, Display, Behavior, and Targeting options

1. Add the trigger to your site depending on the trigger type you chose:

• For Button Click triggers, ensure the element(s) exist on the page and match the configured CSS selector
• For URL Hash, visit a URL that includes the configured hash (e.g. https://example.com/page/#myhash)
• For JavaScript API, call window.GFPopups.show(feedId) (see below)

Setup: Configuring the Popup

This add-on is configured through a Popups feed in Forms → Popups. Each feed represents one popup configuration.

Typical items you’ll configure include:

• Form to Display (which Gravity Form renders in the popup iframe)
• Trigger (button selector, exit intent, timeout, scroll depth, URL hash, or JavaScript API)
• Display (mode, size, animation, backdrop, z-index, and close controls)
• Behavior (dismissal cookie name/duration, respect dismissal, auto-close on submission, preload iframe)
• Targeting (rules that determine where/when the popup is eligible to show)

Using the Add-On: Triggering a Popup

Depending on your selected trigger type:

• Button Click
• Configure a CSS selector in the feed (e.g. .open-popup, #signup-button)
• Add that class/id to an element on the page
• JavaScript API
• Call the API after the page loads (example below)
• Timeout / Exit Intent / Scroll Depth / URL Hash
• Configure the trigger settings in the feed; the popup will display automatically when the trigger condition is met

Logging & Troubleshooting

If your popup isn’t behaving as expected:

• Confirm requirements
• WP 6.0+, PHP 8.0+, Gravity Forms 2.8+
• Confirm the feed is enabled
• Ensure the popup feed is marked Active
• Button-click triggers
• Verify the configured CSS selector matches an element on the page where you expect the popup to open
• Confirm the element exists at the time the popup script runs (e.g., not injected later without re-binding)
• Dismissal cookies
• If “respect dismissal” is enabled, a previously dismissed popup may not re-open until the cookie expires
• For testing, clear site cookies or change the cookie name in the feed
• Iframe / form rendering
• If the form renders but sizing is wrong, confirm the iframe can postMessage back to the parent page (same-site origin expectations apply)
• Caching
• Cookie-based dismissal is “only reliable on non-cached pages”; if you use aggressive page caching, test on an uncached page/session
• Theme template overrides
• If you override templates, verify the override file path is correct:
  • {theme}/gravityformspopups/iframe-form.php

JavaScript API (Trigger Type: “JavaScript API”)

When at least one popup is configured for JavaScript triggering, the frontend initializes:

• window.GFPopups.show(feedId)
• window.GFPopups.hide(feedId)
• window.GFPopups.getPopup(feedId)

Example:

document.addEventListener('DOMContentLoaded', () => {
  if (window.GFPopups) {
    window.GFPopups.show(123); // 123 = popup feed ID
  }
});

Template / PHP Helpers

Useful helper functions include:

• gf_popups_trigger_js($feed_id) → returns a JS snippet like window.GFPopups.show(<feed_id>);
• gf_popups_trigger_script($feed_id) → echoes a <script> tag to trigger on page load
• gf_popups_get_iframe_url($feed_id, $args = []) → iframe URL for a feed
• gf_popups_is_dismissed($feed_id) → checks whether the dismissal cookie exists

Custom Template Conditionals

When using a custom iframe template string, you can conditionally show/hide content depending on whether the current form has been submitted:

• [hide_if_submitted]...[/hide_if_submitted]
• [show_if_submitted]...[/show_if_submitted]