bricks_insert_element
Overview
Insert an element (with optional children) into an existing container on a Bricks page. Unlike bricks_add_section which adds at the page root level, this tool adds elements INSIDE an existing element. Uses the same simplified JSON format as bricks_add_section.
This is essential for adding content to existing sections without replacing them entirely. For example, adding a new card to an existing grid, or appending a CTA button to an existing container. Works across all content areas (main content, header overrides, footer overrides).
Key Features
When to Use
You want to append a new card to an existing grid or card row
You need to add a CTA button or additional text to an existing section
A section was too large for one bricks_add_section call -- add the remaining elements via insert
You are building a section incrementally by adding elements to containers
When NOT to Use
You want to replace an entire section (use bricks_replace_section instead)
You need to move an existing element to a different container (use bricks_move_element instead)
You want to update settings of an existing element (use bricks_update_element instead)
Parameters
page_idnumberREQUIREDparent_idstringREQUIREDelementobjectREQUIREDpositionstringoptionalappend Values: append, prependposition_indexnumberoptionalcontent_areastringoptionalcontent Values: content, header, footerCode Examples
Add a card to an existing grid container
Insert a new card element into an existing 3-column grid on the page.
// Step 1: Find the grid container ID
bricks_get_page_content({ page_id: 42, mode: "summary" })
// Grid container has id: "grid123"
// Step 2: Insert a new card
bricks_insert_element({
page_id: 42,
parent_id: "grid123",
element: {
type: "div",
ref: "new-card",
settings: {},
globalClasses: ["card"],
children: [
{ type: "icon", settings: { icon: "fas fa-globe" } },
{ type: "heading", settings: { tag: "h3", text: "Global Reach" }, globalClasses: ["heading-card"] },
{ type: "text-basic", settings: { text: "Available worldwide." }, globalClasses: ["text-body"] }
]
},
position: "append"
}){
"success": true,
"message": "Element inserted into grid123 on page 42",
"element_ids": { "new-card": "k1l2m3" },
"elements_count": 4
}Prepend a heading inside a container
Add a section label before existing content in a container.
bricks_insert_element({
page_id: 42,
parent_id: "cnt456",
element: {
type: "text-basic",
ref: "section-label",
settings: { text: "OUR SERVICES" },
globalClasses: ["section-label"]
},
position: "prepend"
}){
"success": true,
"element_ids": { "section-label": "n4o5p6" },
"elements_count": 1
}Common Mistakes
bricks_add_section({
page_id: 42,
section: { type: "heading", settings: { text: "New" } }
})
// Creates a new section, not inside existing containerbricks_insert_element({
page_id: 42,
parent_id: "existing-container-id",
element: { type: "heading", settings: { text: "New" }, globalClasses: ["heading-card"] }
})bricks_insert_element({
parent_id: "heading-id", // headings cannot have children!
element: { type: "text-basic", ... }
})bricks_insert_element({
parent_id: "container-id", // container can hold children
element: { type: "text-basic", ... }
})Tips & Warnings
Splitting large sections: If bricks_add_section would exceed the 30-40 element limit, create the section with core structure first, then use bricks_insert_element to add remaining elements into specific containers.
Finding parent IDs: Use bricks_get_page_content in summary mode to find container element IDs. Or use bricks_get_element_by_ref if you set a ref name when creating the container.
Content area matters: If the parent element is in the header override, set content_area to « header ». The tool will not find the element if you use the wrong content area.