bricks_update_element

Phase 4IntermediateComplexity: 5/10
Patch individual element settings (deep merge)

Overview

Update settings of a specific element on a Bricks page. Performs a deep merge — only the provided settings keys are changed, while all other existing settings remain untouched. This is the primary tool for fine-tuning individual elements after they are placed on a page.

Can update text content, CSS styles, responsive breakpoints, global class assignments, and any other element setting. The deep merge means you can update just one typography property without losing the others. Also supports assigning or removing global classes by name.

Key Features

Deep Merge
Only updates the provided keys -- existing settings are preserved. Update one typography property without losing the others.
Global Class Assignment
Assign global classes by name (not ID). Pass globalClasses array to set classes, or empty array to remove all.
Content Area Support
Works on elements in the main content area, header overrides, or footer overrides.
Style Mapper Integration
Settings go through the Style Mapper which auto-remaps aliases, validates values, and ensures Bricks compatibility.

When to Use

You need to change the text content of a specific element
You want to update CSS styles or add responsive breakpoints to an existing element
You need to assign or remove global classes on an element
You are fixing issues found by bricks_validate_page (e.g., adding alt text to images)
You need to update a few elements without rebuilding the whole section
Prerequisites
The page and element must exist. Use bricks_get_page_content to find the element ID. Know the setting key names -- see CLAUDE.md CSS Properties Reference for the complete list of valid keys.

When NOT to Use

You need to update many elements at once (use bricks_bulk_update_elements for up to 100 at a time)
You want to replace an entire section (use bricks_replace_section instead)
You need to add a new element that does not exist yet (use bricks_insert_element instead)
You want to move an element to a new position (use bricks_move_element instead)

Parameters

5 Total Parameters3 Required2 Optional
page_idnumberREQUIRED
Page ID containing the element.
element_idstringREQUIRED
The 6-char Bricks element ID to update.
settingsobjectREQUIRED
Settings to deep merge into the element. Only provided keys are updated. Examples: { "text": "New title" } or { "_typography": { "color": { "hex": "#ff0000" } } }.
globalClassesarrayoptional
Global class NAMES to assign (replaces current assignments). Use empty array [] to remove all classes.
content_areastringoptional
Content area where the element resides.
Default: content Values: content, header, footer

Code Examples

Update heading text and add a class

Change the text of a heading and assign a global class to it.

JSON
bricks_update_element({
  page_id: 42,
  element_id: "d4e5f6",
  settings: {
    "text": "Updated Heading Text"
  },
  globalClasses: ["heading-section"]
})
Response
{
  "success": true,
  "element": {
    "id": "d4e5f6",
    "type": "heading",
    "settings": {
      "tag": "h2",
      "text": "Updated Heading Text"
    },
    "_cssGlobalClasses": ["resolved-class-id"]
  }
}

Add responsive typography to an existing element

Add mobile font size without losing existing desktop typography settings.

JSON
bricks_update_element({
  page_id: 42,
  element_id: "d4e5f6",
  settings: {
    "_typography:mobile_portrait": {
      "font-size": "28px"
    }
  }
})
Response
{
  "success": true,
  "element": {
    "id": "d4e5f6",
    "settings": {
      "_typography": { "font-size": "48px", "font-weight": "700" },
      "_typography:mobile_portrait": { "font-size": "28px" }
    }
  }
}

Common Mistakes

Updating many elements one by one instead of using bulk update
If you need to update more than 3-4 elements, use bricks_bulk_update_elements which performs all updates in a single API call and database write.
Wrong
bricks_update_element({ page_id: 42, element_id: "a1", settings: { text: "A" } })
bricks_update_element({ page_id: 42, element_id: "b2", settings: { text: "B" } })
bricks_update_element({ page_id: 42, element_id: "c3", settings: { text: "C" } })
// 3 API calls, 3 DB writes
Correct
bricks_bulk_update_elements({
  page_id: 42,
  updates: [
    { element_id: "a1", settings: { text: "A" } },
    { element_id: "b2", settings: { text: "B" } },
    { element_id: "c3", settings: { text: "C" } }
  ]
})
// 1 API call, 1 DB write
Expecting the settings to replace instead of merge
Settings are deep-merged, not replaced. To remove a specific setting, you need to set it to an empty value or null explicitly.
Wrong
// Expecting this removes _border
bricks_update_element({
  element_id: "a1",
  settings: { "_typography": { "color": { "hex": "#000" } } }
})
// _border is still there (deep merge)
Correct
// Deep merge: existing _border stays
// Only _typography.color is updated
// Other _typography props preserved too

Tips & Warnings

Tips & Warnings

Deep merge behavior: Only the keys you provide are changed. If an element has _typography with 5 properties and you update with { « _typography »: { « color »: { « hex »: « #000 » } } }, only the color changes — font-size, font-weight, etc. are preserved.

Global classes replace: Unlike settings (merge), globalClasses replaces the entire class list. To add a class without removing existing ones, first read the current classes, then pass the combined list.

Use bricks_bulk_update_elements for multiple updates: For 3+ elements, the bulk tool is significantly more efficient (single API call and DB write).

Return Values

FieldTypeDescription
successbooleanWhether the update was successful.
elementobjectThe updated element with its merged settings.

Related Tools

Technical Details

Tool ID
bricks_update_element
API Endpoint
/bricks-mcp/v1/pages/{page_id}/elements/{element_id}
HTTP Method
PATCH
Namespace
pages-elements
Source File
pages/elements.ts
Version
1.0
Min Bricks Version
1.9
Requires Auth
Yes

Changelog

v1.0
Initial release with deep merge, global class resolution, and content area support.
20250101