---
verified_from: docs-and-ai-memory
bricks_version: 2.x (general)
verification_status: unverified-live — derived from Bricks public docs + AI memory
to_verify: install Bricks on a target then `rolepod_wp_cli_run` to introspect `\Bricks\Elements::$elements` and re-tag
verified_at: 2026-05-28 (metadata added; element list itself NOT live-verified)
---

# Bricks Builder — element catalog + decision rules

Reference for native-first Bricks page builds. **Raw HTML element = last resort.**

> **Accuracy note:** Element names + setting keys below match Bricks 2.x public docs at time of writing, but have NOT been live-verified against a runtime registry. Treat as a planning guide — confirm any specific setting key via the Bricks UI or `\Bricks\Elements` introspection before relying on it in JSON output.

## Detection

- Active THEME: `bricks` (or `bricks-child`). Bricks ships as a theme, not a
  plugin — `rolepod_wp_builder_detect` checks the theme list for it.
- Per-post meta: `_bricks_page_content_2` (JSON array of element objects). A
  page, a header template, and a footer template ALL store their tree in this
  one key — the difference is the post, not the key.
- Data shape: flat array, each item is one element with `id`, `name`, `parent`, `children: []`, `settings: {}`
- See `../builder-formats.md` for the flat-array detail.

## Header/footer templates — do not clobber the page body

A header or footer is a separate post of type `bricks_template`, and its tree
lives in `_bricks_page_content_2` — the same key a page uses for its body.
`rolepod_wp_bricks_write` with `scope: header|footer` therefore refuses any post
that is not a `bricks_template` (`BRICKS_WRONG_POST_TYPE`): writing there would
overwrite that post's page content. Pass the template's own post id, which you
can find with `rolepod_wp_bricks_read(target_id, page_id)` after listing
`bricks_template` posts. `scope: page` writes the page body directly.

## Iron rules

1. Native element FIRST. HTML element (raw HTML wrapper) is a last resort.
2. Bricks elements are FLAT — each has a `parent` id string. Don't nest physically; nest via parent pointer.
3. After build run `rolepod_wp_bricks_read` to verify the round-trip JSON matches what you wrote.

## Free vs Pro

Bricks is a paid product but ALL widgets ship in the base license. No widget tier.

---

## Container primitives

### `container` / `section` / `block` / `div`

Same family; different defaults.

- `container` — outer-most wrapper, max-width applied by default
- `section` — full-width container
- `block` — generic flex/grid box
- `div` — minimal wrapper

```json
{
  "id": "abc123",
  "name": "container",
  "parent": "0",
  "children": ["def456","ghi789"],
  "settings": {
    "_columns": { "desktop": 3 },
    "_padding": { "top": "60", "right": "0", "bottom": "60", "left": "0" },
    "_cssClasses": "wnz-hero"
  }
}
```

---

## Element catalog

### `heading`

H1-H6 + custom HTML tag.

```json
{ "name": "heading", "settings": { "text": "We build websites", "tag": "h1", "_cssClasses": "wnz-hero-h1" } }
```

**Coverage:** 100% headlines.

### `text-basic`

Single-line text (no rich editor).

### `text`

Rich text body. Stores as raw HTML in `settings.text`.

```json
{ "name": "text", "settings": { "text": "<p>Body copy</p>" } }
```

**Coverage:** 100% paragraph blocks.

### `button`

```json
{ "name": "button", "settings": { "text": "Get started", "link": { "type": "external", "url": "..." }, "style": "primary" } }
```

**Coverage:** 100% buttons.

### `image`

Image with optional caption + link.

### `icon`

Single SVG icon. Built-in icon library (Themify, FontAwesome, IonIcons).

### `icon-box`

Icon + heading + text card.

### `counter`

Animated number + label + suffix.

### `accordion`

```json
{ "name": "accordion", "settings": { "accordion": [{"title":"Q1","content":"A1"}] } }
```

### `tabs` / `tabs-nested`

Horizontal/vertical tabs.

### `pricing-tables`

Single pricing tier card — chain multiple in a container row.

```json
{ "name": "pricing-tables", "settings": { "title": "Pro", "price": "49", "features": [...] } }
```

### `posts`

Loop of posts/CPT items.

### `team-members`

Team grid.

### `testimonials`

Testimonial slider.

### `image-gallery`

Static grid.

### `slider`

Image / video carousel.

### `video`

YouTube/Vimeo/self-hosted.

### `nav-menu`

Header menu — pull from WP nav menus.

### `logo`

Site logo.

### `breadcrumbs`

### `form`

Built-in form builder.

### `html`

**LAST RESORT.** Raw HTML.

```json
{ "name": "html", "settings": { "html": "<div class=\"terminal\">...</div>" } }
```

Acceptable for: terminal blocks, marquees, custom SVG illustrations, embeds Bricks doesn't natively support.

### `code`

Inline `<script>` / `<style>` block.

---

## Pattern recipes (Bricks)

### P-001 Hero

```
container (column layout, css "wnz-hero")
├── heading (tag h1)
├── heading (tag h1, with gradient class)
├── text (paragraph)
├── container (row, 2 children) → button × 2
└── container (4 columns) → counter × 4
```

### P-002 Feature grid (3 cards)

```
container (3 columns)
└── 3 × icon-box (icon + title + text)
```

### P-003 FAQ

```
container (1 col)
└── accordion (accordion array)
```

### P-005 Pricing

```
container (3 columns)
└── 3 × pricing-tables
```

Bricks WINS here — pricing-tables is a first-class element. No HTML widget fallback needed.

---

## Helpers + tools

- `rolepod_wp_bricks_read(target_id, page_id)` — read JSON tree
- `rolepod_wp_bricks_write(target_id, post_id, scope, elements, allow_destructive: true)` — write. There is no `backup` parameter: the previous meta value is snapshotted to `wp-content/uploads/rolepod-wp/backups/` ONLY when it already had a value, and `backup_path` comes back `null` when nothing was snapshotted. Check it before assuming you can roll back.
- No widget_schema introspection endpoint yet (Phase 7 candidate). Use this catalog as the reference.