bricks_create_custom_element

Phase 2AdvancedComplexity: 9/10

Create a PHP custom element with controls and render HTML

Overview

Registers a custom Bricks element via PHP in the child theme. Custom elements extend the Bricks element panel with completely bespoke functionality, rendered by PHP templates with full access to WordPress functions and element settings.

Controls define the settings panel that users see in the Bricks builder (text fields, color pickers, repeaters, etc.). The render_html is a PHP template that receives $settings and $element variables and outputs the HTML. Optionally, provide CSS for default styling and a Vue.js builder_template for WYSIWYG editing in the builder.

Use custom elements when built-in Bricks elements and components are insufficient — for example, complex pricing cards with conditional logic, custom post type displays, or third-party API integrations.

Key Features

PHP Rendering

Full PHP template with access to $settings and $element. Use esc_html(), wp_kses(), and any WordPress function for dynamic rendering.

12 Control Types

Supports text, textarea, number, select, checkbox, color, image, repeater, typography, code, link, and rich-text controls for the settings panel.

Nestable Support

Set nestable=true to create container elements that accept other Bricks elements as children, enabling custom layout containers.

Builder Template

Optional Vue.js template for WYSIWYG rendering in the Bricks builder. Supports contenteditable, icon-svg, and reactive settings bindings.

Scoped CSS

Provide default CSS that is automatically scoped to the element class. Supports CSS variables and responsive styles.

When to Use

When built-in Bricks elements cannot achieve the desired functionality
For complex elements with conditional rendering logic (e.g., highlighted pricing card)
When you need PHP access to WordPress functions (WP_Query, get_posts, etc.)
For elements that integrate with third-party APIs or plugins
When you need a nestable container element (set nestable=true)

Prerequisites

A Bricks child theme must be active (the PHP file is saved to the child theme)
Understanding of PHP templating and WordPress functions
Knowledge of Bricks control types (text, textarea, number, select, checkbox, color, image, repeater, etc.)

When NOT to Use

When a built-in Bricks element can achieve the same result (accordion, tabs, icon-box, etc.)
When a Component (bricks_create_component) with properties is sufficient
For simple card layouts that do not require PHP logic
When global classes and standard element types cover the need

Parameters

10 Total Parameters5 Required5 Optional

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

namestringREQUIRED

Unique element name/slug (lowercase, hyphens, e.g., "pricing-card", "testimonial-slider")

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

labelstringREQUIRED

Display label in the Bricks element panel (e.g., "Pricing Card", "Testimonial Slider")

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

categorystringREQUIRED

Element category in the panel (e.g., "custom", "content", "media")

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

iconstringoptional

Dashicon or custom icon class (e.g., "ti-layout-grid2", "dashicons-star-filled")

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

controlsarrayREQUIRED

Array of control definitions. Each has key, type (text/textarea/number/select/checkbox/color/image/repeater/typography/code/link/rich-text), label, and optional default, tab, group, options, placeholder, min, max, required.

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

render_htmlstringREQUIRED

PHP template string for rendering the element. Has access to $settings and $element variables.

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

cssstringoptional

Default CSS for the element (scoped to the element class)

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

scriptsarrayoptional

JavaScript files to enqueue when the element is used (URLs or handles)

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

nestablebooleanoptional

Whether other elements can be nested inside this element (default: false)

Default: false

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

builder_templatestringoptional

Vue.js template for WYSIWYG rendering in the Bricks builder. Receives reactive "settings" and "name" variables.

Code Examples

Pricing Card custom element with PHP rendering

Creates a custom pricing card with plan name, price, period, features repeater, CTA button, and highlighted state. Uses PHP conditionals for the highlighted variant.

JSON

bricks_create_custom_element({
  name: "pricing-card",
  label: "Pricing Card",
  category: "custom",
  controls: [
    { key: "plan_name", type: "text", label: "Plan Name", default: "Starter" },
    { key: "price", type: "text", label: "Price", default: "$29" },
    { key: "period", type: "text", label: "Period", default: "/month" },
    { key: "features", type: "repeater", label: "Features" },
    { key: "cta_text", type: "text", label: "Button Text", default: "Get Started" },
    { key: "highlighted", type: "checkbox", label: "Highlighted", default: false }
  ],
  render_html: "<div class="pricing-card <?php echo !empty($settings['highlighted']) ? 'highlighted' : ''; ?>">n  <h3><?php echo esc_html($settings['plan_name']); ?></h3>n  <div class="price">n    <span class="amount"><?php echo esc_html($settings['price']); ?></span>n    <span class="period"><?php echo esc_html($settings['period']); ?></span>n  </div>n  <ul>n    <?php foreach ($settings['features'] ?? [] as $f): ?>n      <li><?php echo esc_html($f['text'] ?? ''); ?></li>n    <?php endforeach; ?>n  </ul>n  <a href="#" class="btn"><?php echo esc_html($settings['cta_text']); ?></a>n</div>",
  css: ".pricing-card { padding: 40px 30px; border-radius: 12px; background: #fff; box-shadow: 0 2px 12px rgba(0,0,0,0.05); text-align: center; }n.pricing-card.highlighted { border: 2px solid var(--bricks-color-primary); transform: scale(1.05); }n.pricing-card .price .amount { font-size: 48px; font-weight: 700; }n.pricing-card .price .period { font-size: 16px; color: #888; }n.pricing-card ul { list-style: none; padding: 0; margin: 24px 0; }n.pricing-card li { padding: 8px 0; border-bottom: 1px solid #eee; }"
})

Response

{
  "success": true,
  "data": {
    "name": "pricing-card",
    "file": "/wp-content/themes/bricks-child/bricks-mcp/element-pricing-card.php",
    "label": "Pricing Card"
  }
}

Common Mistakes

Using a custom element when a native Bricks element would suffice

Check the list of native rich elements first: accordion, tabs, icon-box, counter, pricing-tables, testimonials, team-members, etc. Only create a custom element when built-in elements cannot achieve the result.

Wrong

// Creating a custom FAQ element from scratch
bricks_create_custom_element({ name: "faq-section", ... })

Correct

// Use the native accordion element instead
{ "type": "accordion", "settings": { "accordions": [...], "faqSchema": true } }

Not escaping output in the PHP template

Always use esc_html(), esc_attr(), esc_url(), or wp_kses_post() when outputting settings values to prevent XSS vulnerabilities.

Wrong

<h3><?php echo $settings['title']; ?></h3>

Correct

<h3><?php echo esc_html($settings['title']); ?></h3>

Forgetting the null coalescing operator for optional settings

Always use ?? for optional settings and repeater fields to avoid PHP warnings when values are not set.

Wrong

<?php foreach ($settings['features'] as $f): ?>

Correct

<?php foreach ($settings['features'] ?? [] as $f): ?>

Tips & Warnings

Tips & Warnings

Child theme required: Custom elements are saved as PHP files in the child theme’s bricks-mcp/ directory. A Bricks child theme must be active.

Control types: The 12 supported types are: text, textarea, number, select, checkbox, color, image, repeater, typography, code, link, and rich-text. Use the appropriate type for the best editing experience.

Nestable elements: Set nestable: true to create container elements that accept child elements. The render_html should include a child rendering placeholder where nested content will appear.

Builder template: For a better editing experience, provide a Vue.js builder_template that mirrors the PHP rendering. This enables WYSIWYG editing with live preview in the Bricks builder.

Return Values

Field	Type	Description
`success`	boolean	Whether the custom element was created successfully
`data.name`	string	Element slug for use in element type references
`data.file`	string	Path to the generated PHP file in the child theme
`data.label`	string	Display label in the Bricks panel

Related Tools

Technical Details

Tool ID

bricks_create_custom_element

API Endpoint

/bricks-mcp/v1/custom-elements

HTTP Method

POST

Namespace

components

Source File

components/custom-elements.ts

Version

1.0

Min Bricks Version

1.9

Requires Auth

Yes

Changelog

v1.0

Initial release

20250101