Meta Box

Breakdance has built-in support for Meta Box. If Meta Box is active, its fields appear in
the dynamic data chooser under a Metabox category, grouped by the field group they
belong to — no configuration, no connecting step.

Create your fields in Meta Box and put real data in at least one post first. Breakdance reads
the field definitions, so an empty field group gives you nothing to bind to and nothing to
preview against.

Using a Meta Box field

1. Select an element and find the control you want to fill — text, an image source, a link
   URL.
2. Click the dynamic data button on that control.
3. Open the Metabox category and find your field under its group.
4. Pick the field.

From there it behaves like any other dynamic field, including the Prepend / Append / Limit
Characters / Fallback options — see Dynamic Data.

Note: the chooser only offers fields the control can accept, so the list changes
depending on what you're binding. An image source and a text control will show different
Meta Box fields from the same field group.

How Meta Box field types map

One Meta Box field can register several entries in the chooser. A single_image field,
for instance, registers both an image field and an image-URL field — same label, different
shapes — and the control you're binding decides which one you get.

Three Meta Box field types are deliberately ignored and never appear in the chooser,
even when they hold data: fieldset_text, file_advanced, and file_upload. Use file
or file_input instead of the two file variants if you need to bind the value.

Tip: don't go looking for repeatable groups in the Metabox category — they get
their own Repeaters category, and they're chosen from the Repeater Field element
rather than from a control's dynamic data button. See below.

Group fields, and their subfields

Meta Box groups get special treatment worth understanding, because it differs from how ACF
groups work.

When Breakdance finds a group, it registers the group itself and walks into it, registering
every subfield as its own dynamic field. So you can bind a single subfield directly,
anywhere on the page, without involving a loop — useful when a group holds one set of
details rather than a repeating list.

The subfield keeps its own plain name. What tells you where it came from is the group
line above it in the chooser, which spells out the full path — the meta box, then the
group, then any nested group:

BD Docs — Meta Box Group Probe - MB Group                  → Group Text
BD Docs — Meta Box Group Probe - MB Group - Nested Group   → Nested Text

So look at the grouping heading, not the field name, to tell two identically-named
subfields apart.

Note: the group field type is not part of free Meta Box — it needs the premium
MB Group extension. Free Meta Box has no group field at all, and it does not say so:
a group defined in code renders in the post editor as an ordinary text box, complete with
a working-looking "+ Add more" button, while silently dropping every subfield. If your
group looks like a single text input in wp-admin, that's what's happening.

Cloneable groups as a repeater

A Meta Box group set to cloneable is a repeating list of rows, and Breakdance renders it
with the Repeater Field element — the same element that
handles ACF repeaters.

1. Build the row design as a Global Block. Go to Breakdance > Global Blocks, create one, and
   bind its elements to the group's subfields. One Global Block describes one row.
2. Add a Repeater Field element to the page or template.
3. In Content → Repeated Block, choose the Global Block from step 1.
4. In Content → Field → Repeater Field, choose your cloneable group. Entries here read
   as the group's name followed by its path in brackets — MB Group (Contact Details - MB Group) — which is how you tell nested groups apart.
5. Lay the rows out with Design → List — grid, slider, accordion and tabs are all
   available, not just a list.

The rows render in the builder canvas and on the front end.

Note: cloneable groups need the premium MB Group extension (see above). On free
Meta Box the Repeater Field dropdown will have nothing from Meta Box to offer.

Because the Repeater Field is a loop, it also gets
alternate and static items and an
empty state. The empty state is worth setting: an
optional group is empty on most posts.

Caution: build the row Global Block from the group's subfields, and build the empty-state
Global Block from static content only. A Global Block that binds post fields breaks when
rendered with no post in context, and takes the page down rather than rendering blank.

Ordering a loop by a Meta Box field

Any Post Loop can sort by a Meta Box value. In the Query
Builder's Order section, set Order By to Meta Box — an extra Field chooser
appears for picking which one — then set Order to ascending or descending.

The Meta Box entry in Order By only appears when Meta Box is active.

What the integration does not do

Unlike ACF, Meta Box has no equivalent of the ACF Relationship query source: there is no
"drive this loop from a Meta Box field" option in the Query Builder's Source dropdown. To
build a loop from Meta Box relationships, use an Array query with the registered relationship ID and direction. MB Relationships stores its connections separately from ordinary post metadata, so a Meta Query is not a substitute for its relationship query.

Field Output Options

• Separator — Text between checkbox-list values.
• Image Index / File Index — Selected item, starting at 0.
• User > Field — Display Name, Bio, or Custom Field; the last uses Custom Field Key.
• Advanced — Type-specific formatting and fallbacks.

Group headings include their nested path. Choose the correct path when subfields share names. A regular group holds one set of values; a cloneable group holds rows and requires MB Group.