bricks_create_component

Phase 2AdvancedComplexity: 8/10

Create a reusable component with configurable properties

Overview

Creates a reusable Bricks Component with configurable properties that connect to internal elements via ref names. Components are the cornerstone of maintainable Bricks sites — they define an element structure once and allow per-instance customization through property connections.

This is the most important tool for avoiding the #2 quality issue: duplicated element structures. Any card, testimonial, feature box, or repeating pattern that appears 3+ times MUST be a component. Each instance uses a single element with componentId and properties instead of duplicating dozens of elements.

Properties map to internal element settings via ref names, so changing « Title » on an instance updates the heading text inside that component instance automatically.

Key Features

Property Connections

Properties connect to internal elements via ref names and setting keys. Example: { "card-title": ["text"] } maps a "Title" property to the text setting of the element with ref "card-title".

Hierarchical Elements

Define the full element tree with type, ref, settings, children, and globalClasses. The Translator processes the tree into Bricks flat format automatically.

Global Class Support

Component elements can reference global classes by name (not ID). Class names are auto-resolved to IDs during creation.

Instance Customization

Each component instance in a section overrides only the properties it needs, keeping the structure and styling from the component definition.

Property Groups

Properties can be organized into named groups (e.g., "Content", "Style") for better usability in the Bricks builder panel.

When to Use

During Phase 2 (Design System) after creating colors, variables, and classes
When any element group (card, feature box, testimonial) will appear 3+ times
When building category cards, service cards, team member cards, pricing cards
Before building sections with repeated patterns — create the component FIRST
When the server raises a "Component Alert" warning about duplicated structures

Prerequisites

Design system should be set up first (colors, variables, global classes)
Global classes referenced by component elements must already exist
Understand the element types and settings format (see CLAUDE.md Element JSON Format)

When NOT to Use

For one-off sections that appear only once on the site
When a pattern appears fewer than 3 times (use global classes instead)
For content that must stay synchronized across all pages — use bricks_create_global_element instead

Parameters

4 Total Parameters2 Required2 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

labelstringREQUIRED

Component display name (e.g., "Hero Card", "Testimonial Slider", "Category Card")

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

categorystringoptional

Component category for organization (e.g., "cards", "heroes", "sections")

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

elementsobjectREQUIRED

Hierarchical element tree for the component. Each element has type, optional ref, optional settings, optional children, and optional globalClasses. Use ref names to connect properties to elements.

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

propertiesarrayoptional

Array of property definitions. Each has label, optional group, optional default, and connections (map of ref_name to array of setting keys). Example: { label: "Title", connections: { "card-title": ["text"] } }

Code Examples

Category Card component with image, icon, title, and description

Creates a reusable card component with 4 configurable properties. Each instance in a section becomes a single element instead of duplicating the entire structure.

JSON

bricks_create_component({
  label: "Category Card",
  category: "cards",
  elements: {
    type: "div", ref: "card-root",
    settings: { "_background": { "color": { "hex": "#ffffff" } }, "_border": { "radius": { "top": "12", "right": "12", "bottom": "12", "left": "12" } }, "_overflow": "hidden" },
    children: [
      { type: "div", children: [
        { type: "image", ref: "card-image", settings: { "_objectFit": "cover" } }
      ]},
      { type: "div", settings: { "_padding": { "top": "20", "right": "20", "bottom": "20", "left": "20" } }, children: [
        { type: "icon", ref: "card-icon", settings: { "_typography": { "font-size": "28px" } } },
        { type: "heading", ref: "card-title", settings: { "tag": "h3" }, globalClasses: ["heading-card"] },
        { type: "text-basic", ref: "card-desc", globalClasses: ["text-body"] }
      ]}
    ]
  },
  properties: [
    { label: "Image", connections: { "card-image": ["image"] } },
    { label: "Icon",  connections: { "card-icon":  ["icon"] } },
    { label: "Title", connections: { "card-title": ["text"] } },
    { label: "Description", connections: { "card-desc": ["text"] } }
  ]
})

Response

{
  "success": true,
  "data": {
    "id": "abc123",
    "label": "Category Card",
    "element_count": 6,
    "properties": [
      { "label": "Image", "connections": { "card-image": ["image"] } },
      { "label": "Icon", "connections": { "card-icon": ["icon"] } },
      { "label": "Title", "connections": { "card-title": ["text"] } },
      { "label": "Description", "connections": { "card-desc": ["text"] } }
    ]
  }
}

// Then use in sections:
{ "type": "div", "componentId": "abc123", "ref": "cat-1", "properties": {
    "Image": { "url": "https://...", "id": 34 },
    "Icon": { "icon": "fas fa-truck", "library": "fontawesome" },
    "Title": "Fourgons utilitaires",
    "Description": "De 4m3 a 15m3"
}}

Common Mistakes

Duplicating element structures instead of using components

Any element group appearing 3+ times MUST be a component. Create the component in Phase 2, then use componentId + properties for each instance.

Wrong

// 6 cards x 10 elements = 60 duplicated elements
{ "type": "div", "settings": { "_background": ..., "_border": ... },
  "children": [
    { "type": "image", "settings": { "image": {...} } },
    { "type": "heading", "settings": { "text": "Card 1", "tag": "h3" } },
    { "type": "text-basic", "settings": { "text": "Description..." } }
  ]
}
// Repeated 6 times with different content

Correct

// 1 component + 6 instances = 7 elements total
bricks_create_component({ label: "Card", elements: {...}, properties: [...] })
// Returns { id: "abc123" }
// Then per instance:
{ "type": "div", "componentId": "abc123", "properties": {
    "Title": "Card 1", "Description": "Description..."
}}

Forgetting ref names on elements that need property connections

Every element that a property connects to MUST have a ref attribute matching the key in the connections map.

Wrong

// No ref on heading — property connection will fail
{ type: "heading", settings: { "tag": "h3" } }
// properties: [{ label: "Title", connections: { "card-title": ["text"] } }]

Correct

// ref matches the connections key
{ type: "heading", ref: "card-title", settings: { "tag": "h3" } }
// properties: [{ label: "Title", connections: { "card-title": ["text"] } }]

Creating components after building sections instead of before

Components must be created in Phase 2 (Design System) BEFORE building page sections. Create the component first, then reference it with componentId.

Wrong

// Phase 4: Build 6 identical cards manually, THEN realize they should be a component

Correct

// Phase 2: Create component FIRST
bricks_create_component({...})
// Phase 4: Use componentId in sections

Tips & Warnings

Critical rule: The Component-First Pattern is the #2 most important quality rule (after using global classes). Any repeated pattern appearing 3+ times MUST be a component.

When to use components vs global elements: Components have configurable properties per instance (different title, image, etc.). Global elements are identical everywhere — editing one updates all instances site-wide. Use components for cards, features, testimonials. Use global elements for shared CTAs, banners, or notices.

Property connections: The connections map uses ref_name as the key and an array of setting keys as the value. For example, { "card-image": ["image"] } maps the property value to the image setting of the element with ref: "card-image".

Payload size: Keep component element trees under 30-40 elements to avoid 502 errors. For very complex components, consider splitting into nested sub-components.

Return Values

Field	Type	Description
`success`	boolean	Whether the component was created successfully
`data.id`	string	Unique component ID — use this as componentId when placing instances in sections
`data.label`	string	Component display name
`data.properties`	array	Resolved property definitions with their connection mappings
`data.element_count`	number	Total number of elements in the component tree

Related Tools

Technical Details

Tool ID

bricks_create_component

API Endpoint

/bricks-mcp/v1/components

HTTP Method

POST

Namespace

components

Source File

components/components.ts

Version

1.0

Min Bricks Version

1.9

Requires Auth

Yes

Changelog

v1.0

Initial release

20250101