bricks_add_section

Phase 4AdvancedComplexity: 8/10

Add a section with hierarchical element JSON to a page

Overview

Add a section to a Bricks page using a hierarchical element tree in simplified JSON format. The server automatically translates the hierarchy into Bricks’ internal flat element format. This is the primary tool for building page content — each call adds one section with its complete element tree.

Sections follow the pattern: section > container > content elements. Use globalClasses for styling, componentId + properties for reusable component instances. The server validates element types, resolves class names to IDs, maps CSS properties, and warns about missing global classes or inline styles.

Key Features

Automatic Translation

Converts hierarchical JSON (section > container > children) into Bricks' internal flat element array format automatically.

Global Class Resolution

Pass class names in globalClasses and the server resolves them to Bricks internal class IDs. No need to look up IDs manually.

Component Instance Support

Use componentId + properties to create instances of reusable components instead of duplicating element structures.

Inline Style Warnings

The server warns when content elements lack global classes, helping enforce the anti-inline-style rule for maintainable pages.

When to Use

You are building page content during Phase 4 (one section per call)
You need to add a hero section, feature grid, testimonials, CTA, or any other section type
You want to add content to an empty page created with bricks_create_page
You need to prepend a section at the top of an existing page

Prerequisites

The page must exist (create with bricks_create_page first). The design system must be ready (Phase 2): colors, spacing variables, global classes, components, and theme styles. Always assign global classes to content elements -- the server warns if elements lack classes.

When NOT to Use

You need to replace an existing section (use bricks_replace_section instead)
You want to insert an element inside an existing container (use bricks_insert_element instead)
You need to add more than 30-40 elements (split into multiple calls or use components)
The design system is not set up yet (complete Phase 2 first)

Parameters

4 Total Parameters2 Required2 Optional

page_idnumberREQUIRED

Target page ID where the section will be added.

sectionobjectREQUIRED

The section element tree in hierarchical JSON format. Must follow section > container > content structure. Each element has type, settings, optional ref, globalClasses, componentId, properties, and children.

positionstringoptional

Where to add the section: append adds at the end of the page, prepend adds at the beginning.

Default: append Values: append, prepend

position_indexnumberoptional

Insert at a specific index among root sections (0-based). Overrides position if provided.

Code Examples

Add a hero section with heading and CTA buttons

A centered hero section following the section > container > content pattern with global classes and responsive breakpoints.

JSON

bricks_add_section({
  page_id: 42,
  section: {
    type: "section",
    ref: "hero-section",
    settings: {
      "_padding": { "top": "120", "bottom": "120" },
      "_padding:mobile_portrait": { "top": "60", "bottom": "60" },
      "_background": { "color": { "hex": "#ffffff" } }
    },
    children: [{
      type: "container",
      settings: {
        "_width": "1200px",
        "_display": "flex",
        "_direction": "column",
        "_alignItems": "center",
        "_gap": "24"
      },
      children: [
        {
          type: "heading",
          ref: "hero-title",
          settings: { tag: "h1", text: "Build Websites with AI" },
          globalClasses: ["text-display"]
        },
        {
          type: "text-basic",
          ref: "hero-subtitle",
          settings: { text: "From prototype to production in minutes." },
          globalClasses: ["text-body"]
        },
        {
          type: "div",
          settings: { "_display": "flex", "_direction": "row", "_gap": "16" },
          children: [
            { type: "button", settings: { text: "Get Started" }, globalClasses: ["btn-primary"] },
            { type: "button", settings: { text: "Learn More" }, globalClasses: ["btn-secondary"] }
          ]
        }
      ]
    }]
  }
})

Response

{
  "success": true,
  "message": "Section added to page 42",
  "element_ids": {
    "hero-section": "a1b2c3",
    "hero-title": "d4e5f6",
    "hero-subtitle": "g7h8i9"
  },
  "elements_count": 7
}

Add a 3-column feature grid with responsive breakpoints

A feature grid that collapses from 3 columns to 1 column on mobile, using global classes for styling.

JSON

bricks_add_section({
  page_id: 42,
  section: {
    type: "section",
    ref: "features",
    settings: { "_padding": { "top": "100", "bottom": "100" } },
    children: [{
      type: "container",
      settings: { "_width": "1200px", "_display": "flex", "_direction": "column", "_gap": "60" },
      children: [
        { type: "heading", settings: { tag: "h2", text: "Features" }, globalClasses: ["heading-section"] },
        {
          type: "div",
          settings: {
            "_display": "grid",
            "_gridTemplateColumns": "1fr 1fr 1fr",
            "_gridTemplateColumns:tablet_portrait": "1fr 1fr",
            "_gridTemplateColumns:mobile_portrait": "1fr",
            "_gap": "30"
          },
          children: [
            { type: "icon-box", settings: { icon: "fas fa-rocket", title: "Fast", content: "Build in minutes." }, globalClasses: ["card"] },
            { type: "icon-box", settings: { icon: "fas fa-shield-alt", title: "Secure", content: "Enterprise-grade." }, globalClasses: ["card"] },
            { type: "icon-box", settings: { icon: "fas fa-code", title: "Flexible", content: "Full control." }, globalClasses: ["card"] }
          ]
        }
      ]
    }]
  }
})

Response

{
  "success": true,
  "element_ids": { "features": "x1y2z3" },
  "elements_count": 8
}

Common Mistakes

Payload too large (more than 30-40 elements per call)

Large sections with 50+ elements can cause 502 timeout errors. Split complex sections into multiple bricks_add_section calls, or use components to reduce element count. The server retries 502/503/504 automatically with backoff.

Wrong

bricks_add_section({
  page_id: 42,
  section: {
    // 60+ elements in one call
    // ... massive JSON tree ...
  }
})
// 502 Gateway Timeout

Correct

// Split into smaller calls
bricks_add_section({ page_id: 42, section: { /* section 1: ~25 elements */ } })
bricks_add_section({ page_id: 42, section: { /* section 2: ~25 elements */ } })
// Or use components to reduce element count

Missing section > container hierarchy

Every section must follow the section > container > content pattern. The container constrains width (typically 1200px) and provides the flex/grid layout context.

Wrong

{
  type: "section",
  children: [
    { type: "heading", settings: { text: "Title" } }
  ]
}
// Heading is not inside a container!

Correct

{
  type: "section",
  children: [{
    type: "container",
    settings: { "_width": "1200px" },
    children: [
      { type: "heading", settings: { text: "Title" } }
    ]
  }]
}

No responsive breakpoints on grid layouts

Every grid must include responsive breakpoints to collapse columns on smaller screens. Without this, content overflows on mobile devices.

Wrong

{
  "_display": "grid",
  "_gridTemplateColumns": "1fr 1fr 1fr",
  "_gap": "30"
}
// 3 columns on mobile = overflow!

Correct

{
  "_display": "grid",
  "_gridTemplateColumns": "1fr 1fr 1fr",
  "_gridTemplateColumns:tablet_portrait": "1fr 1fr",
  "_gridTemplateColumns:mobile_portrait": "1fr",
  "_gap": "30"
}

Content elements without global classes (inline styles)

Every heading, text, button, and icon element must have at least one global class. The server warns when elements lack classes. Create classes in Phase 2 and assign via globalClasses array.

Wrong

{ type: "heading", settings: {
  text: "Title",
  "_typography": { "font-size": "36px", "font-weight": "600" }
}}
// Inline styles = unmaintainable

Correct

{ type: "heading", settings: { text: "Title" },
  globalClasses: ["heading-section"]
}
// Class handles all styling

Tips & Warnings

30-40 element limit: Keep each bricks_add_section call under 30-40 elements to avoid 502 timeouts. Use components to reduce element count for repeated patterns like card grids.

Use ref names: Always set ref on important elements. The response maps ref names to generated IDs, which you need for bricks_update_element, bricks_set_dynamic_data, etc.

Global classes are mandatory: The server warns when ANY content element (heading, text, button, icon) lacks a global class. If you see this warning, stop and create the missing classes before continuing.

Responsive is not optional: Every grid needs mobile breakpoints. Every section needs reduced mobile padding. Every large heading needs a smaller mobile font size.

Return Values

Field	Type	Description
`success`	boolean	Whether the section was added successfully.
`element_ids`	object	Map of ref names to generated Bricks element IDs (6-char hex). Use these IDs for subsequent operations.
`elements_count`	number	Total number of elements created in this section.
`warnings`	array	Anti-inline-style warnings if content elements lack global classes.
`unresolved_classes`	array	List of class names that could not be resolved to IDs (class does not exist).

Related Tools

Technical Details

Tool ID

bricks_add_section

API Endpoint

/bricks-mcp/v1/pages/{page_id}/sections

HTTP Method

POST

Namespace

pages-elements

Source File

pages/sections.ts

Version

1.0

Min Bricks Version

1.9

Requires Auth

Yes

Changelog

v1.0

Initial release with hierarchical JSON translation, global class resolution, component support, and inline style warnings.

20250101