bricks_replace_section
Overview
Replace an existing section on a Bricks page with entirely new content. The tool identifies the section by its root element ID and removes it along with all its child elements, then inserts the new section tree in its place. Uses the same simplified JSON format as bricks_add_section.
This is useful for redesigning a specific section without affecting the rest of the page. The old section is completely removed — there is no merge or partial update.
Key Features
When to Use
The existing section has too many issues to fix individually with bricks_update_element
You want to rebuild a section with a different layout (e.g., change from 2-column to 3-column)
You are iterating on a design and want to replace the current version with an improved one
When NOT to Use
You want to add a new section without removing anything (use bricks_add_section instead)
You want to remove a section without adding a replacement (use bricks_delete_section instead)
You need to update multiple elements with small changes (use bricks_bulk_update_elements instead)
Parameters
page_idnumberREQUIREDsection_idstringREQUIREDsectionobjectREQUIREDCode Examples
Replace a hero section with a new design
Find the old hero section ID, then replace it with an updated version.
// Step 1: Find the section ID
bricks_get_page_content({ page_id: 42, mode: "summary" })
// Returns section with id: "a1b2c3"
// Step 2: Replace the section
bricks_replace_section({
page_id: 42,
section_id: "a1b2c3",
section: {
type: "section",
ref: "new-hero",
settings: { "_padding": { "top": "140", "bottom": "140" } },
children: [{
type: "container",
settings: { "_width": "1200px" },
children: [
{ type: "heading", settings: { tag: "h1", text: "New Hero Title" }, globalClasses: ["text-display"] },
{ type: "text-basic", settings: { text: "Updated subtitle." }, globalClasses: ["text-body"] }
]
}]
}
}){
"success": true,
"element_ids": { "new-hero": "x9y8z7" },
"elements_count": 4
}Common Mistakes
bricks_replace_section({
page_id: 42,
section_id: "def456", // This is a container, not the section!
section: { ... }
})// Find root sections first
bricks_get_page_content({ page_id: 42, mode: "summary" })
// Use the section-type element at root level
bricks_replace_section({
page_id: 42,
section_id: "abc123", // Root section element
section: { ... }
})Tips & Warnings
Complete replacement: This tool removes ALL children of the old section. Any element IDs from the old section become invalid. If other tools reference those IDs, they will fail.
Same payload limits apply: Keep the replacement section under 30-40 elements, just like bricks_add_section.
Find section IDs: Use bricks_get_page_content({ mode: « summary » }) and look for elements with type: « section » and parent: 0.