bricks_load_cdn_library

Phase 4.5IntermediateComplexity: 4/10
Load a known library (AOS, GSAP, Swiper, etc.) with auto-init

Overview

Loads a CDN library into the site by injecting the required <link>/<script> tags and optional initialization code. Handles everything automatically: CDN URLs, async loading, deduplication, and DOMContentLoaded wrapper for init scripts.

Available libraries: AOS, GSAP+ScrollTrigger, Animate.css, Lenis, Typed.js, Splitting.js, CountUp.js, tsParticles, Vanta.js, Swiper, Lottie Player, GLightbox, CSS Marquee.

Key Features

Auto CDN URLs
No need to remember CDN URLs or version numbers — the catalog handles it
Deduplication
Checks for existing URLs before injecting to avoid double-loading
Auto initialization
Default init scripts are wrapped in DOMContentLoaded and injected automatically
Custom init override
Provide custom_init to override the default initialization script

When to Use

Phase 4.5 (CDN Enhancement) to add visual design enhancements
Loading scroll animations (AOS), smooth scrolling (Lenis), or text effects (Typed.js)
When the library is in the built-in catalog — this handles CDN URLs automatically
Prerequisites
Design system and templates should be ready first (Phase 4.5 comes after Phase 4)
Check bricks_list_cdn_libraries for available library IDs and usage hints

When NOT to Use

For libraries NOT in the catalog — use bricks_load_custom_cdn instead
If the library is already loaded — the tool deduplicates automatically, but check first
Avoid loading more than 2-3 JS libraries per site

Parameters

5 Total Parameters1 Required4 Optional
librarystringREQUIRED
Library ID to load (e.g., "aos", "gsap", "lenis", "typed-js")
Values: aos, gsap, animate-css, lenis, typed-js, splitting-js, countup-js, tsparticles, vanta-js, swiper, lottie-player, glightbox, css-marquee
scopeenumoptional
Where to inject: "global" (site-wide) or "page" (single page)
Default: global Values: global, page
page_idnumberoptional
Page ID (required when scope is "page")
custom_initstringoptional
Custom init JS to use instead of the default
skip_initbooleanoptional
Skip injecting the init script (useful for custom init later)
Default: false

Code Examples

Load AOS globally

Add scroll reveal animations site-wide, then use data-aos attributes on elements

JSON
{
    "library": "aos",
    "scope": "global"
}
Response
{"success": true, "actions": ["✓ Injected 1 CSS asset(s) into global header", "✓ Injected 1 JS asset(s) into global footer", "✓ Injected init script into global footer"], "usageHint": "Add data-aos="fade-up" via element _attributes"}

Common Mistakes

Loading AOS but forgetting data-aos attributes on elements
Every element you want animated needs data-aos="fade-up" (or similar) via _attributes
Loading too many JS libraries
Max 2-3 JS libraries per site. Pick ONE scroll animation lib (AOS or GSAP, not both)
Loading globally for a single page
Use scope: "page" with page_id for single-page usage

Tips & Warnings

Tips & Warnings
  • All JS is loaded with defer for non-blocking performance
  • Init scripts are wrapped in DOMContentLoaded automatically
  • Use skip_init: true if you want to write custom initialization via bricks_add_custom_js
  • Load globally only if used on 3+ pages; otherwise use page scope

Return Values

FieldTypeDescription
successbooleanWhether the library was loaded successfully
actionsarrayList of actions taken (injected CSS, JS, init script, or skipped)
usageHintstringHow to use the library with Bricks elements

Related Tools

Technical Details

Tool ID
bricks_load_cdn_library
API Endpoint
/bricks-mcp/v1/custom-code (multiple calls)
HTTP Method
POST
Namespace
wordpress-site
Source File
wordpress/cdn-libraries.ts
Version
1.0
Min Bricks Version
1.9
Requires Auth
Yes

Changelog

v1.0
Initial release
20250101