bricks_delete_element
Overview
Delete an element and all its children from a Bricks page. The parent element’s children array is automatically updated to maintain valid structure. This removes a single element (and its descendants) from within a section, unlike bricks_delete_section which removes an entire root-level section.
After deletion, the parent container still exists with its remaining children. If you delete the only child of a container, the container remains but will be empty.
Key Features
When to Use
You want to clean up unwanted elements without removing the entire section
You are fixing layout issues by removing elements that cause problems
An element needs to be replaced -- delete it first, then insert a new one with bricks_insert_element
When NOT to Use
You want to replace an element with a new one in the same operation (no atomic replace -- delete then insert)
You want to hide an element conditionally (use bricks_set_element_conditions instead)
You want to move the element, not delete it (use bricks_move_element instead)
Parameters
page_idnumberREQUIREDelement_idstringREQUIREDcontent_areastringoptionalcontent Values: content, header, footerCode Examples
Delete a card from a grid
Remove a specific card element from a grid container. The grid and other cards remain.
// Step 1: Find the element to delete
bricks_get_page_content({ page_id: 42, mode: "summary" })
// Find card with id: "card03"
// Step 2: Delete it
bricks_delete_element({
page_id: 42,
element_id: "card03"
}){
"success": true,
"deleted_count": 4,
"deleted_ids": ["card03", "icon03", "heading03", "text03"]
}Delete an element from a header override
Remove an element from the header content area of a page.
bricks_delete_element({
page_id: 42,
element_id: "extra-btn",
content_area: "header"
}){
"success": true,
"deleted_count": 1,
"deleted_ids": ["extra-btn"]
}Common Mistakes
bricks_delete_element({
element_id: "grid-container"
})
// Removes the entire grid + all cards!bricks_delete_element({
element_id: "card-to-remove"
})
// Only removes the specific cardbricks_delete_element({
element_id: "section-root-id"
})
// Works but not semantically clearbricks_delete_section({
page_id: 42,
section_id: "section-root-id"
})
// Clear intent: removing a sectionTips & Warnings
Verify before deleting: Use bricks_get_page_content in summary mode to verify the element type and children before deleting. Removing the wrong element can break page layout.
Cascading deletion: All children are removed recursively. If you delete a div with 10 child elements, all 11 elements are removed.
Not undoable via API: Deleted elements cannot be recovered through the API. WordPress revision history may contain the previous state, restorable with bricks_restore_revision.