Skip to main content

Modals (Popups)

Modals let you define a popup once — a lead-capture form, an announcement, a video — and open it from any button on any page, or automatically on triggers like scroll depth or exit intent. This guide covers creating modals, wiring them to buttons, the auto-open triggers, and the frequency rules that keep popups from annoying your visitors (or hurting your search rankings).

What Modals Are​

A modal is a reusable overlay: content defined once, referenced by ID, opened on demand. It is not a section (sections live in the page flow; a modal floats above it), and its content follows your design system automatically — surface color, corner radius, typography, and a light or dark theme variant per modal, with no modal-specific global settings to manage.

Modals are managed alongside Reusable Elements in the Promptless WP admin, and each one has:

  • A title — an admin label so you can find it again; visitors never see it
  • Content — rich text, buttons, an image or video, or a form (see below)
  • A size — how wide the panel renders
  • A theme variant — light or dark, resolving all your smart colors accordingly
  • Triggers and frequency rules — when it opens and how often (the rest of this guide)

What Goes Inside​

Modal content is deliberately a focused subset: rich text, buttons, an image or video embed, and — the flagship use — a form. Full layout sections (Post Grids, Pricing tables, FAQs) don't belong inside a modal: those assume page width and section spacing, and a modal is a card, not a page. If you find yourself wanting a whole section in a popup, that content probably deserves its own page.

Forms in modals are the primary use case and work end to end: the form submits without a page reload, the success message renders inside the modal, and multi-step forms navigate their steps inside the dialog without scrolling the page behind it. You can optionally have the modal close itself a few seconds after a successful submit.

Opening a Modal from a Button​

Any button in any section can target a modal instead of a URL. In the button's settings, choose the modal as the target — the button then opens the popup instead of navigating. A button targets either a URL or a modal, never both.

This click-trigger path is the workhorse: "Get a quote" buttons that open a form modal, "Watch the demo" buttons that open a video, pricing-page buttons that open a contact form pre-framed for that plan.

For hand-authored content outside Promptless sections, adding data-aisb-modal-open="{modal-id}" to any element makes it a trigger too.

Auto-Open Triggers​

Modals can also open themselves, per page or site-wide:

  • Page load — opens after a delay you set. A minimum delay of 3 seconds is enforced; instant popups convert worse and read as hostile.
  • Scroll depth — opens when the visitor has scrolled 25%, 50%, or 75% of the page. The gentlest auto-trigger: it fires only for visitors already engaged with the content.
  • Exit intent — opens when the mouse leaves through the top of the window (heading for the close button or address bar). Desktop only — the gesture doesn't exist on touch devices, so on phones this trigger simply never fires.

Auto-open modals attach to specific pages via a target list, or site-wide. Site-wide auto-open is allowed but the UI warns you — a popup that fires on every page of a visit is rarely the intent.

Mobile and Your Search Rankings​

Google penalizes sites that show intrusive popups on mobile page load. Promptless defaults to the compliant posture: auto-open triggers are OFF on mobile viewports unless you explicitly override per modal — and the override comes with a warning. This is a ranking-protection default, not a style opinion; think hard before overriding it.

Frequency Capping​

Auto-open triggers require a frequency rule so the same visitor isn't hit repeatedly:

  • Every visit — no capping; use sparingly
  • Once per session — resets when the browser session ends
  • Once per visitor (default) — remembered for about 30 days
  • Once ever — never again for that visitor

Two behaviors worth knowing:

  • Editing a modal re-arms it. The dismissal memory is tied to the modal's content and trigger configuration, so when you meaningfully change a modal, visitors who dismissed the old version will see the new one once. You never need to manually "reset" a campaign.
  • Converting counts as dismissing. A visitor who submits the form inside a modal won't see it auto-open again, same as if they'd closed it.

Click-triggered opens ignore capping entirely — an explicit click always opens the modal.

Accessibility (Built In)​

Every modal follows the standard dialog pattern with nothing to configure: focus moves into the dialog on open and is trapped there, Escape closes it, clicking the backdrop closes it (you can disable backdrop-close for must-acknowledge messages), a visible close button is always present, focus returns to the triggering button on close, page scrolling locks while the modal is open, and entrance animations respect visitors' reduced-motion preference.

Design and Usage Tips​

  • One job per modal. A form modal asks for the lead; a video modal shows the video. Modals that try to do both convert worse than either alone.
  • Prefer click triggers. A visitor who clicks "Get a quote" has told you they want the form. Auto-open triggers borrow attention; spend that credit deliberately — exit intent and deep scroll are the defensible ones.
  • Match the theme to the page. A dark modal over a light page reads as an interruption; matching variants read as part of the site.
  • Write the button as the promise. "Get my free estimate" on the trigger, then a form headline that repeats the promise — continuity between click and popup is what keeps the visitor in the flow.

Connector Support​

Modals are fully manageable through the Promptless Connector — Claude can create, update, list, and delete them, wire section buttons to them, and set triggers, targeting, and frequency rules conversationally: "Create an exit-intent modal for the pricing page with our consultation form, once per visitor."