bricks_add_interaction

Phase 4AdvancedComplexity: 7/10

Add hover, click, scroll, or load animations to elements

Overview

Adds an interaction to a Bricks element, enabling dynamic behavior triggered by user actions or page events. Each interaction consists of a trigger (what initiates it), an action (what happens), and a target (which element is affected). Bricks supports 30+ trigger types including click, hover, scroll, enterView, contentLoaded, form events, WooCommerce events, and AJAX query events.

Interactions are stored in the element’s settings._interactions[] array and are processed by Bricks’ built-in interaction engine on the frontend. Multiple interactions can be stacked on a single element, enabling complex sequential animations and conditional behaviors.

Key Features

30+ Trigger Types

Supports element triggers (click, hover, focus, blur), viewport triggers (enterView, leaveView), page triggers (scroll, contentLoaded), form events, WooCommerce cart events, AJAX query events, and animation chaining (animationEnd).

20+ Action Types

Actions include show/hide, CSS class manipulation (add/remove/toggle), startAnimation, scrollTo, setAttribute, JavaScript execution, toggleOffCanvas, togglePopup, browser storage operations, and query loadMore.

Flexible Targeting

Target the element itself (self), any element via CSS selector (custom), or a popup template (popup). Custom selectors enable targeting multiple elements at once.

Storage-Based Conditions

Attach conditions to interactions that check window, session, or local storage values before firing. Supports comparison operators: exists, notExists, ==, !=, >=, <=, >, <.

Animation Chaining

Use the animationEnd trigger to create sequential animation chains where one animation starts after another completes, enabling sophisticated multi-step motion design.

When to Use

Add hover animations to cards, buttons, or interactive elements
Trigger scroll-based reveal animations when elements enter the viewport
Show or hide elements on click (toggle menus, accordions, modals)
Chain animations using the animationEnd trigger for sequential effects
Add scroll-to-section behavior to navigation links
Run custom JavaScript functions on specific events
Toggle off-canvas menus or popups based on user interactions
Add storage-based conditional behaviors (show once, remember dismissal)

Prerequisites

Page and element must already exist
Element ID must be known (6-character hex ID from bricks_get_page_content)
For target: "custom", the CSS selector must match existing elements
For target: "popup", the popup template must already exist

When NOT to Use

For simple CSS hover effects — use _cssTransition and hover pseudo-class in global classes instead
For element visibility based on WordPress data — use bricks_set_element_conditions
For page-level scroll animations — consider AOS library via bricks_load_cdn_library for simpler implementation

Parameters

12 Total Parameters4 Required8 Optional

page_idnumberREQUIRED

The WordPress page (post) ID containing the element.

element_idstringREQUIRED

The 6-character Bricks element ID to add the interaction to.

interaction.triggerstringREQUIRED

What triggers the interaction.

Values:

click, hover, mouseOver, mouseLeave, focus, blur, enterView, leaveView, animationEnd, scroll, contentLoaded, mouseleaveWindow, formSubmit, formSuccess, formError, ajaxStart, ajaxEnd, filterOptionEmpty, filterOptionNotEmpty, wooAddedToCart, wooAddingToCart, wooRemovedFromCart, wooUpdateCart, wooCouponApplied, wooCouponRemoved

interaction.actionstringREQUIRED

What happens when the interaction is triggered.

Values:

show, hide, addClass, removeClass, toggleClass, startAnimation, setAttribute, removeAttribute, toggleAttribute, scrollTo, javascript, toggleOffCanvas, clearForm, loadMore, storageAdd, storageRemove, storageCount, togglePopup, openAddress, closeAddress

interaction.targetstringoptional

Which element is affected by the action.

Default: self Values: self, custom, popup

interaction.targetSelectorstringoptional

CSS selector when target is "custom". Targets all matching elements.

interaction.animationTypestringoptional

CSS animation name for the startAnimation action (e.g., "fadeIn", "slideUp", "bounceIn").

interaction.animationDurationstringoptional

Duration for the startAnimation action (e.g., "0.6s", "600ms").

interaction.classNamestringoptional

CSS class name for addClass, removeClass, or toggleClass actions.

interaction.runOncebooleanoptional

If true, the interaction fires only on the first trigger occurrence.

Default: false

interaction.jsFunctionstringoptional

JavaScript function name for the javascript action (no parentheses).

content_areastringoptional

Content area where the element resides.

Default: content Values: content, header, footer

Code Examples

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

Fade-in animation on scroll into view

Add an enterView interaction that triggers a fadeIn animation when a card element scrolls into the viewport.

JSON

bricks_add_interaction({
  page_id: 42,
  element_id: "abc123",
  interaction: {
    trigger: "enterView",
    action: "startAnimation",
    target: "self",
    animationType: "fadeIn",
    animationDuration: "0.6s",
    rootMargin: "0px 0px -10% 0px",
    runOnce: true
  }
})

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

Toggle class on click with custom target

Add a click interaction on a button that toggles an "active" class on a sibling menu element using a CSS selector.

JSON

bricks_add_interaction({
  page_id: 42,
  element_id: "btn456",
  interaction: {
    trigger: "click",
    action: "toggleClass",
    target: "custom",
    targetSelector: ".mobile-nav-menu",
    className: "is-open"
  }
})

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 2018

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

For basic CSS hover transitions (color change, scale, shadow), use _cssTransition and pseudo-class selectors in global classes. Interactions are for more complex behaviors like class toggling, visibility changes, and animations.

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 2018

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 runOnce: true, enterView animations re-trigger every time the element scrolls in and out of view, creating a distracting repeat effect. Set runOnce: true for one-time reveal animations.

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 2018

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

The startAnimation action requires animationType to specify which CSS animation to play. Without it, nothing visible happens.

Tips & Warnings

Multiple interactions: You can add multiple interactions to the same element. Each one is appended to the _interactions array. Use bricks_list_interactions to see all interactions on an element.

Animation chaining: Create sequential animations by using animationEnd as the trigger on the next element, referencing the previous interaction’s ID via animationId.

Storage conditions: Use interactionConditions to create smart behaviors like « show banner only if not dismissed » by checking localStorage for a dismissal flag.

Return Values

Field	Type	Description
`success`	boolean	Whether the interaction was successfully added to the element.
`message`	string	Confirmation with the element ID and interaction summary.
`interaction_index`	number	The 0-based index of the newly added interaction in the element's _interactions array.

Related Tools

Technical Details

Tool ID

bricks_add_interaction

API Endpoint

/bricks-mcp/v1/pages/{page_id}/elements/{element_id}/interactions

HTTP Method

PUT

Namespace

pages-elements

Source File

pages/interactions.ts

Version

1.0

Min Bricks Version

1.9

Requires Auth

Yes

Changelog

v1.0

Initial release with full Bricks interaction system support: 30+ triggers, 20+ actions, storage conditions, and animation chaining.

20250101