Meta Box

Mosaic reads your Meta Box field groups and turns every field into a variable you can drop anywhere
where variables are supported. You don’t need to write any code or shortcodes.

This page lists exactly what Mosaic supports, which variables each field type produces, and whether a
field gives you a simple variable or a loop.

Supported plugin and add-ons

Mosaic works with the free Meta Box plugin, with Meta Box AIO, and with the individual premium
extensions. Meta Box splits its features across add-ons, and what Mosaic can read depends on which of
them you have active:

What you want to read	Needs
Fields on posts, pages, and custom post types	Meta Box (free)
Fields on taxonomy terms	MB Term Meta
Fields on users	MB User Meta
Fields on settings pages	MB Settings Page
Group fields (nested, repeatable)	MB Group
Relationships between posts, terms, and users	MB Relationships
Fields stored in a custom database table	MB Custom Table

Mosaic detects each add-on at runtime, so a context simply doesn’t appear until the add-on that
provides it is active.

Mosaic Pro is required to output custom field values. In Mosaic Free the Meta Box variables still
show up in the variable picker, but they appear locked and resolve to an empty value.

What Mosaic supports

Custom post types and taxonomies

Post types and taxonomies you register with MB Custom Post Type (or with any other plugin, or with
code) are picked up by Mosaic automatically. Each one becomes its own dynamic source, so you can build a
loop over it, sort it, filter it, and use its archive as a template.

The only requirement is that the post type or taxonomy is registered as public. Private,
admin-only post types are intentionally left out of the list.

Custom fields

Mosaic reads Meta Box fields in these places:

Where your field group is attached	Supported	Notes
Posts, pages, and any custom post type	Yes	Meta Box free
Taxonomy terms	Yes	Needs MB Term Meta
Users	Yes	Needs MB User Meta
Settings pages	Yes	Needs MB Settings Page. Accessed through the Dynamic sources field. See Settings pages
Relationships	Yes	Needs MB Relationships. See Relationships
Comments	Not supported	MB Comment Meta fields aren’t read
Navigation menus and menu items	Not supported	Meta Box has no menu fields
Blocks	Not supported	Our Post Content element can render the Blocks’ output, but Mosaic doesn’t read the block’s own fields

Settings pages

Mosaic lists every Meta Box settings page that stores its values the normal way (in the WordPress
options table). Network pages and customizer-only pages are skipped, because those save into
site options or into the customizer instead.

Beyond outputting values

Your Meta Box fields are also available in these Mosaic features:

• Order by: order a post, term, or user loop by a custom field. Mosaic knows the field type,
  so numbers sort as numbers and dates sort as dates instead of as text.
• Loop filters: show only the posts, terms, or users whose custom field matches a condition.
• Conditions: show or hide any element based on a custom field value.
• @ATTACHMENT(): turn an attachment ID from an Image, File, Video, or Media field into a URL,
  optionally at a specific WordPress image size.

Important: ordering and loop filtering both work on the raw value stored in the database, not
on the value the variable outputs. The two are often different, because Meta Box enriches the value when
it’s read. An Image field stores an attachment ID but outputs a URL; a Post field stores a post ID but
outputs a title; a Select field stores the option key but can output the label. So compare against
what’s stored, not against what you see on the page. See
Sorting and filtering by a custom field for the details.

How your fields appear in Mosaic

Variable names and labels

Every field becomes one or more variables. In the variable picker they’re labeled with a Meta Box
prefix and the field’s own name, so they’re easy to find:

Meta Box / Subtitle
Meta Box / Hero image / Image
Meta Box / Hero image / ID

The variable name behind the label is built from the field’s ID:

Context	Variable name
Post, term, and user fields	meta_<field ID>
Settings page fields	option_<field ID>

When a field produces more than one variable, the extra ones get a suffix, for example
meta_hero_image__id, meta_link__title, meta_location__latitude. The main variable of a field
never carries a suffix.

For fields that point at another object (Post, User, Taxonomy), the main variable is the title or
name, with the ID and URL available beside it.

Simple variables vs. loops

This is the most important distinction on this page.

• A simple variable holds one value. You drop it straight into a text element, an image, a link, a
  background, or anywhere else Mosaic accepts a variable.
• A loop holds a list of values. Typically you need to add these as a loop, and Mosaic repeats its
  content once per item. Inside the loop you use the row’s own variables.

Two Meta Box settings decide this for most field types:

• Multiple: the field holds several selections, so it becomes a loop.
• Clone: the field is repeatable, so it becomes a loop.

Some field types are collections by nature and always loop whatever those settings say (galleries, file
fields, Key Value, Text List, Fieldset Text, Checkbox List, Group). And when a field is both Multiple
and Clone, you get a loop of loops. See Clone and Multiple together.

Every loop also gives you a Record index variable, so you can number your items.

Value types

Each variable carries a type, which tells Mosaic where it can be used: Text, HTML, URL,
Image URL, or Number. An Image URL variable can be dropped directly onto an image element; an
HTML variable is output without escaping; a Number variable sorts numerically.

Field type reference

Below, “simple” and “loop” describe the field with Clone and Multiple off. Turning either on makes
the field a loop whose rows expose the same variables.

Text and basic fields

Field type	Simple or loop	Variables	Value type
Text, Textarea, Password, Color, Icon, Sidebar, and other plain types	Simple	meta_<field>	Text
Number, Range, Slider	Simple	meta_<field>	Number
Checkbox, Switch	Simple	meta_<field>	Number (1 or empty)
URL, File Input	Simple	meta_<field>	URL
Date, Datetime, Time	Simple	meta_<field>	Text

Meta Box has a long list of field types, and any type without special handling becomes a single plain
text variable holding the stored value. That’s the sensible result for types like Color, Icon, Password,
and Sidebar, and it also means a field type Mosaic doesn’t specifically know about still works rather
than disappearing.

Date, Datetime, and Time follow how the field is configured to save. With Save as timestamp
turned on, Mosaic formats the timestamp using the field’s own PHP format. Otherwise the stored string is
output as-is, which is also what Meta Box itself displays. Either way, sorting treats these as real
dates and times.

Fields that only draw the editing UI and store nothing (Heading, Divider, Custom HTML,
Button, and Tab) produce no variables, because there’s no value to output.

Content fields

Field type	Simple or loop	Variables	Value type
WYSIWYG, Block Editor	Simple	meta_<field>	HTML
oEmbed	Simple	meta_<field>: the embed code (HTML) meta_<field>__url: the entered URL	HTML / URL

WYSIWYG and Block Editor output rendered HTML wrapped in Mosaic’s own content structure, the same
wrapper the “Post content” variable uses. That’s deliberate: it means your global theme styles apply to
the field’s content just as they do to post content. Block Editor content is rendered from its block
markup first, so blocks come out as real HTML.

oEmbed resolves the stored media URL into the provider’s embed code. The result is cached so the same
URL isn’t fetched again on every page load.

Media fields

Every media field exposes the attachment’s URL and its ID.

Field type	Simple or loop	Row / field variables
Single Image	Simple	meta_<field>: the image URL (Image URL) meta_<field>__id: the attachment ID
Image, Image Advanced, Image Upload	Loop	value: the image URL (Image URL) value__id: the attachment ID
File, File Upload, File Advanced, Media	Loop	value: the file URL value__id: the attachment ID
Video	Loop	value: the video URL value__id: the attachment ID

Only Single Image holds one item; the rest are galleries or multi-file fields. Meta Box stores them
as lists, so they always come through as loops.

Image fields give you the full-size original URL. If you need a specific WordPress image size, pass
the ID variable through @ATTACHMENT().

Choice fields

Field type	Simple or loop
Select, Radio, Button Group, Select Advanced, Input List	Simple
Checkbox List, Autocomplete, Select Tree	Loop (they always hold a list)

All of them expose the same pair: the stored option key, plus the label from the field’s options list:

	Variables
Simple	meta_<field>: the stored value (Text) meta_<field>__label: the label (Text)
Loop	value: the stored value value__label: the label

If a stored value isn’t in the field’s options list any more, Mosaic falls back to showing the stored
value itself rather than rendering nothing, so imported or renamed data stays visible.

Image Select is the one exception in this family. Its options map to image URLs rather than to text,
so instead of a label you get an image:

• meta_<field>: the stored option key (Text)
• meta_<field>__image: the option’s image URL (Image URL)

Relational fields

These fields point at another object. The main variable is the object’s title or name, with its ID
and URL beside it, so a reference is useful both as text and as a link.

Field type	Simple or loop	Variables
Post	Simple	meta_<field>: the post title meta_<field>__id: the post ID meta_<field>__url: the permalink
User	Simple	meta_<field>: the display name meta_<field>__id: the user ID meta_<field>__url: the author archive URL
Taxonomy, Taxonomy Advanced	Simple	meta_<field>: the term name meta_<field>__id: the term ID meta_<field>__url: the term archive URL

With Multiple turned on, each of these becomes a loop whose rows expose value, value__id, and
value__url.

When one of these fields holds many selections, Mosaic loads the referenced posts, users, or terms in a
single batched query rather than one lookup per row, so a long list stays fast.

Structured fields

Field type	Simple or loop	Variables
Link	Simple	meta_<field>: the URL meta_<field>__title: the link text meta_<field>__target
Map, Open Street Map	Simple	meta_<field>__latitude, meta_<field>__longitude, meta_<field>__zoom
Background	Simple	meta_<field>: the image URL (Image URL) meta_<field>__color, __position, __size, __repeat, __attachment, __css
Key Value	Loop	value: the value value__key: the key
Fieldset Text	Loop	value: the text value__key: the sub-field key
Text List	Loop	value: the text

Map and Open Street Map have no single main variable, so pick the coordinate parts you need.

Background gives you the individual pieces plus a ready-made __css value, which is handy when you
want to apply the whole background in one place.

Key Value, Fieldset Text, and Text List are lists by nature, so they always loop.

Group fields

The Group field (MB Group add-on) holds other fields, so it always becomes a loop. Add the loop,
and inside it every sub-field is available as its own variable, named value_<sub-field ID>, plus the
same suffixes described above (__id, __label, __url, and so on).

Setup	Rows
Group	Exactly one row
Group with Clone turned on	One row per repeat

A non-repeating group holds a single set of values, so it’s a loop with exactly one row. Adding it as a
loop is what gives you access to its sub-fields.

Nesting works. A group inside a group, a gallery inside a group, a multi-select inside a repeatable
group: each nested field becomes a nested loop inside its parent’s loop, as deep as you need.

One thing to know about sub-fields: inside a group, Meta Box stores the plain stored value rather than
the enriched one it returns for a top-level field. Mosaic resolves those back to the same shape, so a
sub-field produces the same variables as it would at the top level.

Clone and Multiple together

This combination is specific to Meta Box and worth understanding, because it produces a loop inside a
loop.

Settings	What you get
Neither	A simple variable
Multiple only	One loop, one row per selection
Clone only	One loop, one row per repeat
Clone and Multiple	An outer loop with one row per repeat, and inside each row a nested loop with one row per selection

The same applies to a field that’s already a collection by nature: cloning a gallery, a Text List, or a
Fieldset Text gives you an outer loop per repeat, each containing a nested loop of that repeat’s items.

Relationships

With the MB Relationships add-on, each relationship you define appears as a loop of the connected
objects. This works from posts, terms, and users, and it doesn’t need the Term Meta or User Meta add-ons.
Connections are read from the relationships table directly.

Relationship loops expose the same variables as a reference field: value (the title or name),
value__id, and value__url.

Both directions are available. From an object on the “from” side you get the connected “to” objects,
and from an object on the “to” side you get the connected “from” objects. A reciprocal relationship
registers a single side, so it appears once.

A “has one” relationship is still offered as a loop. It simply has at most one row.

Custom Table storage

Mosaic supports the MB Custom Table add-on, where a field group’s values move out of the WordPress
meta tables into one row per object with one column per field.

Outputting values, ordering, filtering, and conditions all work against the custom table. You don’t need
to configure anything. Mosaic resolves where each field’s values live and builds its queries
accordingly.

Two things to know:

• If a column can’t be addressed (for example the field was removed from a hand-managed table), Mosaic
  fails closed: a filter on it matches nothing and a sort on it is dropped, rather than silently
  reading from the wrong place.
• A Clone or Group field occupies a single column holding a combined value, exactly as it occupies a
  single meta row. Ordering and filtering on such a field isn’t meaningful in either storage mode.

Sorting and filtering by a custom field

You can order a post, term, or user loop by a Meta Box field, and filter a loop by one. Mosaic uses
the field type to compare values correctly:

Field type	Sorted as
Number, Range, Slider	Number
Date, Datetime	Date and time
Time	Time
Everything else	Text

There’s also an Auto option, which inspects the stored values and picks the comparison for you. Auto
is especially useful with MB Custom Table, where every column is stored as text whatever the field holds.

These work on the stored value, not the output

Ordering, filtering, and conditions are resolved in the database, against the value Meta Box saved.
Variables are different: they’re resolved when the page is built, and Meta Box enriches the value on the
way out. So the value you filter against is often not the value you see rendered.

Here’s what’s actually stored for the field types where this catches people out:

Field type	What’s stored	What the variable outputs
Single Image, Image, File, Media, Video	The attachment ID	A URL
Post	The post ID	The title, plus ID and URL
User	The user ID	The display name, plus ID and URL
Taxonomy Advanced	The term ID	The term name, plus ID and URL
Select, Radio, Button Group, Checkbox List, and other choice fields	The option key	The key and its label
Image Select	The option key	The key and the option’s image URL
Date, Datetime, Time	Whatever the field saves: a formatted string, a custom save format, or a Unix timestamp	The formatted date or time
Checkbox, Switch	1, or empty when off	1 or empty
oEmbed	The entered URL	The embed code, plus the URL

Because the Date fields’ storage is configurable, check how yours is set up before writing a filter
value. A timestamp and a formatted date compare very differently.

A few field types can’t be filtered or sorted usefully at all:

• The plain Taxonomy field saves through WordPress’s own term assignment and writes no meta value
  anywhere. Mosaic knows this, so it isn’t offered as a sort or filter target at all. A clause on it
  could only ever match nothing. Use Taxonomy Advanced instead, which stores term IDs in a meta value
  and works normally.
• Multi-value and repeatable fields store their whole list as one combined value. That covers
  anything with Multiple or Clone, plus collection fields like galleries, Key Value, or Text List.
  Comparisons against it are unreliable, so filter on something else.
• Group stores its whole content as one combined value, and its sub-fields aren’t offered as sort
  or filter targets. You can still output them inside the loop, and you can use a condition inside the
  loop to skip rows you don’t want.

Limitations at a glance

• Custom field values require Mosaic Pro. In Mosaic Free the variables are visible but locked.
• Heading, Divider, Custom HTML, Button, and Tab fields store no value, so they produce no variables.
• Fields on comments aren’t read, and neither are the fields belonging to MB Blocks.
• Meta Box has no navigation menu or menu item fields, so those contexts don’t apply.
• Settings pages that are network or customizer-only aren’t listed, because they store their
  values elsewhere.
• The plain Taxonomy field can’t be sorted or filtered on. Use Taxonomy Advanced when you need that.
• A multi-value field (a gallery, Checkbox List, a Multiple select, and so on) is only available as a
  loop. There’s no single variable that outputs the whole list at once.