bricks_create_popup

Phase 4AdvancedComplexity: 7/10

Create a popup with triggers and display rules

Overview

Creates a Bricks popup template with a trigger, display conditions, and appearance settings. Popups support six trigger types (load, scroll, exit_intent, click, timed, inactivity), frequency control (once, every_visit, always), AJAX lazy-loading for performance, and configurable position, animation, and overlay. This is the primary tool for building newsletter signups, exit-intent offers, cookie consent, and promotional popups.

Key Features

Six trigger types

Supports load (page load), scroll (distance), exit_intent (mouse leaves viewport), click (element), timed (delay), and inactivity (idle user).

Frequency control

Show once (cookie-based with configurable days), every visit, or always. Plus per-page, per-session, and total lifetime limits.

AJAX lazy-loading

Load popup content via AJAX on trigger instead of on page load — improves page performance.

Rich animations

Entry animations (fadeIn, slideUp, slideDown, slideLeft, slideRight, zoomIn) and exit animations with configurable duration.

Flexible positioning

Nine screen positions: center, top-center, top-left, top-right, bottom-center, bottom-left, bottom-right, center-left, center-right.

When to Use

When creating newsletter signup popups
When building exit-intent promotional offers
When adding cookie consent or GDPR notices
When creating announcement bars triggered by scroll or load delay
When building click-triggered modal dialogs (e.g., video lightbox, pricing details)

Prerequisites

Design system should be set up (colors, classes) for consistent popup styling
Content for the popup should be planned before creation
Display conditions should be decided (which pages show the popup)

When NOT to Use

When building a regular page section — use bricks_add_section instead
When you want a sticky header/footer element — use bricks_create_template with type "header"/"footer"
When the popup should have no automatic trigger (click-only from a specific element) — create the popup first, then use bricks_create_popup_trigger

Parameters

6 Total Parameters3 Required3 Optional

titlestringREQUIRED

Popup title (e.g., "Newsletter Signup", "Exit Intent Offer").

contentobjectoptional

Initial element tree for the popup content (same format as template content).

triggerobjectREQUIRED

Trigger configuration: type (load/scroll/exit_intent/click/timed/inactivity), delay (ms), scroll_distance, scroll_unit (px/%), repeat (once/every_visit/always), cookie_days.

popup_settingsobjectREQUIRED

Appearance settings: width, height, position, animation, animation_out, animation_duration, overlay_color, close_on_overlay_click, close_on_esc, show_close_button, disable_page_scroll, z_index, limit_per_page, limit_per_session, limit_total, ajax_load.

conditionsarrayoptional

Display conditions controlling on which pages the popup is available. Same format as template conditions.

statusstringoptional

Popup template status.

Default: publish Values: publish, draft

Code Examples

Warning: Undefined array key "example_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 10

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 1939

Create an exit-intent newsletter popup

JSON

{
  "tool": "bricks_create_popup",
  "params": {
    "title": "Newsletter Signup",
    "trigger": {
      "type": "exit_intent",
      "repeat": "once",
      "cookie_days": 30
    },
    "popup_settings": {
      "width": "600px",
      "height": "auto",
      "position": "center",
      "animation": "zoomIn",
      "animation_out": "fadeOut",
      "animation_duration": "0.3s",
      "overlay_color": "rgba(0,0,0,0.6)",
      "close_on_overlay_click": true,
      "close_on_esc": true,
      "show_close_button": true,
      "disable_page_scroll": true
    },
    "conditions": [{ "main": "any" }],
    "status": "publish"
  }
}

Response

{
  "popup_id": 42,
  "title": "Newsletter Signup",
  "trigger": { "type": "exit_intent", "repeat": "once", "cookie_days": 30 },
  "conditions": [{ "main": "any", "id": "a1b2c3" }]
}

Common Mistakes

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 1939

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49

Without frequency control, popups show on every page load which annoys visitors. Always set repeat to "once" with a reasonable cookie_days value (7-30 days) for promotional popups.

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 1939

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49

If the popup contains images or complex content, set ajax_load: true so it does not impact initial page load performance.

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 1939

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49

Exit intent does not work on mobile devices (no mouse cursor). Consider adding a timed or scroll trigger as a mobile fallback.

Tips & Warnings

Mobile consideration: Exit intent triggers rely on mouse movement detection, which does not exist on mobile. For mobile visitors, consider using a scroll-based trigger (e.g., 50% page scroll) or a timed trigger (e.g., 30 seconds delay) as a fallback.

Performance: Set ajax_load: true for popups with heavy content (images, forms, videos). This loads the popup HTML only when triggered, not on initial page load.

Click triggers: To trigger a popup from a specific button, first create the popup without a trigger, then use bricks_create_popup_trigger to link a button element to the popup.

Return Values

Field	Type	Description
`popup_id`	number	The new popup template post ID.
`title`	string	Popup title.
`trigger`	object	Applied trigger configuration.
`conditions`	array	Applied display conditions.

Related Tools

Technical Details

Tool ID

bricks_create_popup

API Endpoint

/bricks-mcp/v1/popups

HTTP Method

POST

Namespace

templates

Source File

templates/popups.ts

Version

1.0

Min Bricks Version

1.9

Requires Auth

Yes

Changelog

v1.0

Initial release

20250101