bricks_get_element_by_ref

UtilityBeginnerRead OnlyComplexity: 2/10

Find an element by its ref/label name

Overview

Finds a Bricks element by its ref/label name on a specific page. Returns the element ID, type, settings, and optionally a summary of its children. This is the primary way to locate elements that were created with a specific ref name in bricks_add_section, avoiding the need to parse the full page content.

Key Features

Ref-based lookup

Finds elements by their human-readable ref/label name instead of opaque 6-character IDs.

Optional children summary

Can include a summarized tree of child elements, useful for understanding the element's structure.

Content area support

Searches within a specific content area (content, header, footer).

When to Use

When you assigned a ref name during bricks_add_section and need to find the element ID later
When you need to update or target a specific element but only know its label/ref name
When building multi-step workflows where you create elements in one step and modify them in another
When you need to find the ID of a grid container, loop item, or other structural element

Prerequisites

Page must exist with Bricks content
The element must have a ref/label name assigned (set via the "ref" field in bricks_add_section)

When NOT to Use

When searching for elements by content text — use bricks_search_content instead
When you already know the element ID — use bricks_get_page_content or bricks_update_element directly
When you need to find elements across multiple pages — use bricks_search_content instead

Parameters

4 Total Parameters2 Required2 Optional

page_idnumberREQUIRED

Page ID to search within.

refstringREQUIRED

Element ref/label name to find.

include_childrenbooleanoptional

Include summarized children tree in response.

Default: false

content_areastringoptional

Content area to search.

Default: content Values: content, header, footer

Code Examples

Warning: Undefined array key "example_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 10

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 1935

Find a grid container by ref name

JSON

{
  "tool": "bricks_get_element_by_ref",
  "params": {
    "page_id": 33,
    "ref": "features-grid",
    "include_children": true
  }
}

Response

{
  "id": "abc123",
  "type": "div",
  "settings": {
    "_display": "grid",
    "_gridTemplateColumns": "1fr 1fr 1fr",
    "_gap": "30"
  },
  "children": [
    { "id": "def456", "type": "div", "label": "card-1" },
    { "id": "ghi789", "type": "div", "label": "card-2" },
    { "id": "jkl012", "type": "div", "label": "card-3" }
  ]
}

Common Mistakes

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 1935

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49

The ref/label name must have been explicitly set via the "ref" field when the element was created with bricks_add_section. Elements without a ref cannot be found by this tool.

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 1935

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49

The ref is a custom label you assigned, not the element type. For example, "hero-title" is a ref name, while "heading" is the element type.

Tips & Warnings

Multi-step workflow: The typical pattern is: (1) bricks_add_section with ref names on key elements, (2) bricks_get_element_by_ref to find element IDs, (3) bricks_set_query_loop or bricks_set_dynamic_data targeting those IDs. Always assign refs to elements you plan to modify later.

Return Values

Field	Type	Description
`id`	string	The 6-character Bricks element ID.
`type`	string	Element type (e.g., "div", "heading", "section").
`settings`	object	Full element settings object.
`children`	array	Summarized children tree (only when include_children is true).

Related Tools

Technical Details

Tool ID

bricks_get_element_by_ref

API Endpoint

/bricks-mcp/v1/pages/{page_id}/elements/by-ref

HTTP Method

GET

Namespace

pages-elements

Source File

pages/utilities.ts

Version

1.0

Min Bricks Version

1.9

Requires Auth

Yes

Changelog

v1.0

Initial release

20250101