bricks_update_custom_code

Phase 4.5IntermediateComplexity: 4/10
Update global custom CSS or JavaScript

Overview

Adds custom JavaScript globally or to a specific page. Injects code into either the header (before </head>) or footer (before </body>). Supports append mode (add after existing) or replace mode (overwrite entirely).

Critical: Bricks outputs customScriptsBodyFooter raw into HTML. JavaScript code must be wrapped in <script> tags or it will render as visible text on the page.

Key Features

Position control
Inject in header (before </head>) or footer (before </body>)
Append or replace
Add to existing code or overwrite completely
Dual scope
Global (site-wide) or page-specific injection

When to Use

Adding custom initialization scripts for CDN libraries
Injecting tracking or analytics code
Adding custom animations or interactions via JavaScript
Page-specific JavaScript functionality
Prerequisites
For page scope, you need the page_id
If using append mode, check existing code first with bricks_get_custom_code

When NOT to Use

For loading CDN libraries — use bricks_load_cdn_library instead (handles tags + init automatically)
For CSS — use bricks_add_custom_css instead

Parameters

5 Total Parameters4 Required1 Optional
jsstringREQUIRED
JavaScript code to add (without tags)
scopeenumREQUIRED
Where to add: "global" or "page"
Values: global, page
page_idnumberoptional
Page ID (required for page scope)
positionenumREQUIRED
Where in HTML to inject: "header" or "footer"
Values: header, footer
modeenumREQUIRED
Append to existing or replace entirely
Values: append, replace

Code Examples

Add GSAP animation to footer

Inject a GSAP scroll animation globally in the footer

JSON
{
    "js": "gsap.from(".feature-card", { scrollTrigger: ".features-grid", y: 60, opacity: 0, stagger: 0.15 });",
    "scope": "global",
    "position": "footer",
    "mode": "append"
}
Response
{"success": true}

Common Mistakes

JS code renders as visible text on the page
Bricks outputs customScriptsBodyFooter raw — JS must be wrapped in tags. The CDN library loader does this automatically, but bricks_add_custom_js does NOT
Wrong
console.log("hello")
Correct
<script>console.log("hello")</script>

Tips & Warnings

Tips & Warnings

CRITICAL: JavaScript MUST be wrapped in <script> tags when stored in customScriptsBodyFooter. Bricks renders this content raw into HTML via frontend.php.

  • The bricks_load_cdn_library tool handles script tag wrapping automatically
  • When using this tool directly, the agent must provide raw JS — consider wrapping
  • Use footer position for most scripts (deferred loading)

Return Values

FieldTypeDescription
successbooleanWhether the code was added successfully

Related Tools

Technical Details

Tool ID
bricks_update_custom_code
API Endpoint
/bricks-mcp/v1/custom-code
HTTP Method
PUT
Namespace
wordpress-site
Source File
wordpress/custom-code.ts
Version
1.0
Min Bricks Version
1.9
Requires Auth
Yes

Changelog

v1.0
Initial release
20250101