bricks_update_component

UtilityIntermediateComplexity: 6/10
Update an existing component

Overview

Updates an existing Bricks Component. You can modify the label, category, element tree, and/or properties. When updating elements, the entire element tree is replaced — partial updates to individual elements within a component are not supported.

This tool is essential for iterating on component designs during development. If you need to add a new property, change the internal structure, or fix styling on a component, use this tool rather than deleting and recreating it, which would break existing instances.

Key Features

Partial Updates
Only the provided fields are updated. You can change just the label, just the properties, or just the elements without affecting the others.
Element Replacement
When elements are provided, the entire tree is replaced. All existing instances will render with the new structure while keeping their property values.
Instance Preservation
Updating a component does not break existing instances. Property values set on instances are preserved as long as the property labels remain the same.

When to Use

When you need to change a component's internal structure or add new elements
When adding or modifying configurable properties on an existing component
When renaming or recategorizing a component for better organization
When fixing styling or layout issues discovered during page building
After creating a component, if you realize it needs additional properties
Prerequisites
The component must already exist (get its ID from bricks_get_components)
If updating elements, the new element tree must include all ref names used by existing properties
Existing instances on pages will use the updated structure

When NOT to Use

When you want to create a brand new component — use bricks_create_component
When you want to delete a component entirely — use bricks_delete_component
For minor tweaks to individual instances — update the instance properties directly

Parameters

5 Total Parameters1 Required4 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
component_idstringREQUIRED
ID of the component to update (obtained from bricks_get_components or bricks_create_component)

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
labelstringoptional
New component display name

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
New category for organization

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
elementsobjectoptional
New element tree (replaces existing). Must include ref names for any property connections.

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
Updated component properties. Each has label, optional group, optional default, and connections map.

Code Examples

Add a new property to an existing component

Adds a "Link" property to a card component so each instance can have a different URL.

JSON
bricks_update_component({
  component_id: "abc123",
  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"] } },
    { label: "Link", connections: { "card-root": ["link"] } }
  ]
})
Response
{
  "success": true,
  "data": {
    "id": "abc123",
    "label": "Category Card",
    "properties": [...]
  }
}

Common Mistakes

Updating elements without including ref names used by properties
When replacing the element tree, ensure all ref names referenced in property connections are still present in the new tree.
Wrong
// Removes the element with ref "card-title" but properties still reference it
bricks_update_component({ component_id: "abc123", elements: { type: "div", children: [...] } })
Correct
// New tree still includes ref "card-title"
bricks_update_component({ component_id: "abc123", elements: { type: "div", children: [
  { type: "heading", ref: "card-title", settings: { "tag": "h3" } }, ...
] } })

Tips & Warnings

Tips & Warnings

Element replacement is total: When you provide elements, the entire tree is replaced. There is no partial element update within a component — provide the complete tree.

Property label matching: Existing instances store property values keyed by label. If you rename a property label, instances will lose that value. Keep labels stable once components are in use.

Check usage first: Before making breaking changes, run bricks_get_component_usage to see how many instances exist across the site.

Return Values

FieldTypeDescription
successbooleanWhether the component was updated successfully
data.idstringComponent ID (unchanged)
data.labelstringUpdated component display name
data.propertiesarrayUpdated property definitions

Related Tools

Technical Details

Tool ID
bricks_update_component
API Endpoint
/bricks-mcp/v1/components/{component_id}
HTTP Method
PUT
Namespace
components
Source File
components/components.ts
Version
1.0
Min Bricks Version
1.9
Requires Auth
Yes

Changelog

v1.0
Initial release
20250101