Advanced Custom Fields · Secure Custom Fields

Mosaic reads your ACF and SCF 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 plugins

Plugin	Supported
Advanced Custom Fields (free)	Yes
Advanced Custom Fields PRO	Yes
Secure Custom Fields (SCF)	Yes

Mosaic works the same way with all three. It doesn’t matter which one you use. Mosaic detects whichever is active and reads its field groups.

A few field types (Repeater, Flexible Content, Gallery, Clone) and Options Pages are only available in ACF PRO. Secure Custom Fields includes all of them for free, so if you’re on SCF everything on this page is available to you.

Mosaic Pro is required to output custom field values. In Mosaic Free the ACF/SCF 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 ACF/SCF (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 ACF/SCF fields in these places:

Where your field group is shown	Supported	Notes
Posts, pages, and any custom post type	Yes	Includes location rules such as post type, specific post, category, page template, post format, post status
Taxonomy terms	Yes	Category, tag, and any custom taxonomy
Users	Yes	User profile fields
Navigation menus	Yes	Menu-level fields
Navigation menu items	Yes	Per-menu-item fields
Options pages	Yes	Options pages can usually be accessed through the Dynamic sources field. See Options pages.
Attachments (media)	Yes	Fields on media items. See Attachments
Comments	Not supported
Widgets	Not supported
Blocks	Not supported	Our Post Content element can render the Gutenberg blocks, but we don’t modify the block. So this integration is not relevant for Mosaic.

Attachments

Fields you add to media items work like any other post fields. Media is a post type, so you can build a loop over your media library and your attachment fields show up inside it, and they’re available when you’re working with a single attachment too. Ordering and filtering a media loop by one of these fields works the same way it does for posts.

One difference from the WordPress admin: ACF lets you limit an attachment field group to certain file types (“Attachment is equal to image/png”). Mosaic offers those fields on every attachment. A media loop can hold a mix of file types, and the field list has to be settled before Mosaic knows which file each row holds, so restricting by file type would mean the first item in the loop decided which fields existed for all the others. A field that doesn’t apply to a given file simply resolves to an empty value, so it’s safe to bind. If you want to hide it, use a condition.

Options pages

Mosaic lists every ACF/SCF options page that stores its values the normal way (in the WordPress options table). If you changed an options page to save into a different place (for example into a specific post or user via Permissions > Custom Storage), Mosaic doesn’t list that page as an options page. Those values are stored as custom fields of that post or user, so you can read them there instead.

Editor vs. front end

In the Mosaic editor, Mosaic deliberately shows you a slightly wider set of fields than the front end will show a visitor. If a field group is limited to certain user roles or logged-in users, you can still build with it in the editor, but at render time it only resolves for visitors who match the rule. That’s how ACF’s own rules work, and it means you can design for a state you’re not currently in.

Beyond outputting values

Your ACF/SCF fields are also available in these Mosaic features:

• Order by: order a post, term, user, or menu 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, users, or menus 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, Gallery, or Icon Picker 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 ACF/SCF formats the value when it’s read. An Image field stores an attachment ID but outputs a URL; a Post Object field stores a post ID but can output 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 an ACF prefix and the field’s own label, so they’re easy to find:

ACF / Subtitle
ACF / Hero image
ACF / Hero image / ID

The variable name behind the label is built from the field name:

Context	Variable name
Post, term, user, menu, menu item fields	meta_<field name>
Options page fields	option_<field name>

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

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.

Whether a field is a simple variable or a loop depends on the field type, and for some types on the field’s own settings (for example, a Select with Multiple turned on becomes a loop).

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

Mosaic supports every field type ACF and SCF offer, with these exceptions, which are layout-only and store no value at all, so there is nothing to output:

• Message
• Accordion
• Tab
• Separator

If you use a custom or third-party ACF field type that Mosaic doesn’t know, you still get one simple text variable holding the raw stored value.

Basic fields

Field type	Simple variable or loop	Variables	Value type
Text	Simple	meta_<field>	Text
Text Area	Simple	meta_<field>	Text
Number	Simple	meta_<field>	Number
Range	Simple	meta_<field>	Number
Email	Simple	meta_<field>	Text
URL	Simple	meta_<field>	URL
Password	Simple	meta_<field>	Text

Content fields

Field type	Simple variable or loop	Variables	Value type
WYSIWYG Editor	Simple	meta_<field>	HTML
oEmbed	Simple	meta_<field>	HTML (the embed code)
Image	Simple	see below	see below
File	Simple	meta_<field>	Number (attachment ID) or URL
Gallery	Loop	see below	see below

Image. What you get depends on the field’s Return Format:

Return Format	Variables
Image Array	meta_<field>: the image URL (Image URL) meta_<field>__id: the attachment ID (Number)
Image ID	meta_<field>: the image URL (Image URL) meta_<field>__id: the attachment ID (Number)
Image URL	meta_<field>: the image URL (Image URL)

With the Array and ID formats, Mosaic derives the URL from the attachment ID at full size. If you need a specific WordPress image size, use the ID variable with @ATTACHMENT().

File. With the File Array and File ID formats you get the attachment ID; with File URL you get the file URL. There’s no separate URL companion variable for files, because the attachment ID already resolves to the file. Use @ATTACHMENT() if you need the URL.

Gallery is always a loop, whatever its Return Format. Each row gives you:

Return Format	Row variables
Image Array / Image ID	value: the image URL (Image URL) value__id: the attachment ID (Number)
Image URL	value: the image URL (Image URL)

Choice fields

All four of these share the same behavior. With the Return Format set to Value or Label you get one variable holding that string. With Both (Array) you get the stored value plus its human-readable label.

Field type	Simple variable or loop
Select	Loop when Multiple is on, otherwise simple
Checkbox	Loop (always)
Radio Button	Simple
Button Group	Simple

Return Format	Variables (simple)	Row variables (loop)
Value or Label	meta_<field>: Text	value: Text
Both (Array)	meta_<field>: the stored value (Text) meta_<field>__label: the label (Text)	value: the stored value value__label: the label

True / False is a separate case: it’s a simple variable holding 1 or 0 as a Number, so an unchecked field outputs 0 rather than nothing.

Relational fields

These fields point at another object. The main variable is always the object’s ID. Where ACF hands Mosaic the whole object (that is, where the Return Format is set to the object rather than the ID), you also get its name and its URL for free, with no extra database queries.

Field type	Simple variable or loop	Variables
Post Object	Loop when Multiple is on, otherwise simple	meta_<field> (ID), and with the Post Object return format also meta_<field>__label (Title) and meta_<field>__url
Relationship	Loop (always)	value (ID), and with the Post Object return format also value__label (Title) and value__url
Page Link	Loop when Multiple is on, otherwise simple	meta_<field>: the page URL
Taxonomy	Loop when the appearance is Checkbox or Multi Select, otherwise simple	meta_<field> (Term ID), and with the Term Object return format also meta_<field>__label (Name) and meta_<field>__url
User	Loop when Multiple is on, otherwise simple	meta_<field> (User ID), and with the User Array or User Object return format also meta_<field>__label (Name) and meta_<field>__url (author archive)

When one of these fields is a loop, the row variables are value, value__label, and value__url instead of the meta_... names.

If the Return Format is set to the plain ID, Mosaic gives you the ID variable only. It doesn’t look up each object to fill in a name and a URL, so a long list of references stays fast.

Advanced fields

Field type	Simple variable or loop	Variables
Link	Simple	see below
Color Picker	Simple	meta_<field>: Text
Date Picker	Simple	meta_<field>: Text
Date Time Picker	Simple	meta_<field>: Text
Time Picker	Simple	meta_<field>: Text
Google Map	Simple (many variables)	see below
Icon Picker	Simple (one variable per tab)	see below
Nav Menu	Simple	see below

Link.

Return Format	Variables
Link Array	meta_<field>: the URL (URL) meta_<field>__title: the link text (Text) meta_<field>__target: the target, e.g. _blank (Text)
Link URL	meta_<field>: the URL (URL)

Color Picker. Hex String and RGBA String are passed through as they are. RGBA Array is converted into a ready-to-use CSS color: rgb(1, 2, 3) when the color is fully opaque, rgba(18, 171, 52, 0.5) when it isn’t.

Date, Date Time, and Time Picker output the value using the field’s own Return Format setting, so what you see in Mosaic is what you configured in ACF. For sorting, Mosaic still treats these as real dates and times rather than as text.

Google Map produces one variable per address part. There’s no single “main” variable, so pick the parts you need:

meta_<field>__address, __lat, __lng, __zoom, __place_id, __name, __street_number, __street_name, __street_name_short, __city, __post_code, __country, __country_short

Latitude, longitude, and zoom are Numbers; the rest are Text. If another plugin adds extra data to the ACF map field, a developer can extend this list with a filter.

Icon Picker (Array return format) gives you one variable per tab the field has enabled:

Variable	Holds
meta_<field>__dashicons	the Dashicon class name
meta_<field>__media_library	the attachment ID of the chosen image
meta_<field>__url	the icon URL

Only the variable matching the tab the icon was picked from has a value; the others are empty. That’s what lets you build one layout that handles every icon source. To render a media library icon, pass meta_<field>__media_library through @ATTACHMENT().

With the String return format the Icon Picker is a single Text variable instead.

Nav Menu. The field’s Save Format decides what you get: Nav Menu Object and Nav Menu ID both give you the menu ID as a text variable, and Nav Menu (HTML) gives you the rendered menu markup as HTML.

Repeater, Group, Flexible Content, and Clone

These four field types hold other fields, so they always become loops. Add the loop, and inside it every sub-field is available as its own variable, named value_<sub-field name> (plus the same suffixes described above: __id, __label, __url, and so on).

Field type	Becomes	Rows
Repeater	Loop	One row per repeater row
Group	Loop	Exactly one row
Clone (Group display)	Loop	Exactly one row
Clone (Seamless display)	Not a loop	Its sub-fields appear as normal top-level fields
Flexible Content	Loop	One row per layout row

Group and Clone (Group) hold a single set of values, so they’re loops with exactly one row. Adding them as a loop is what gives you access to their sub-fields.

Clone (Seamless) is flattened: its sub-fields show up alongside your other fields, exactly as they do in the WordPress editor. Clone’s “Prefix Field Names” option is handled for you, so you’ll see the original field names.

Flexible Content rows can each come from a different layout, so Mosaic gives every layout’s sub-fields their own variables, labeled with the layout name:

Layout A / Heading    →  value_layout_a_heading
Layout B / Image      →  value_layout_b_image

You also get a Flexible Content Layout Name variable (value_acf_fc_layout) holding the layout of the current row. Use it with a condition to render each layout differently. A layout’s variables resolve only on rows that actually use that layout, so two layouts can safely reuse the same sub-field name.

Nesting works. A Repeater inside a Repeater, a Group inside a Flexible Content layout, a Gallery inside a Repeater: each nested field becomes a nested loop inside its parent’s loop, as deep as you need.

Sorting and filtering by a custom field

You can order a post, term, user, or menu loop by any ACF/SCF field, and filter a loop by one. Mosaic uses the field type to compare values correctly:

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

There’s also an Auto option, which inspects the stored values and picks the comparison for you.

A note on Repeater, Group, Flexible Content, and Clone: sorting and filtering work on single field values. The sub-values inside these container fields aren’t offered as sort or filter targets.

These work on the stored value, not the output

Ordering, filtering, and conditions are resolved in the database, against the value ACF/SCF saved. Variables are different: they’re resolved when the page is built, and ACF/SCF formats the value on the way out based on the field’s Return Format. 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
Image, File, Gallery	The attachment ID	A URL (depending on Return Format)
Post Object, Relationship, Page Link	The post ID	The ID, and optionally the title or URL
Taxonomy	The term ID	The ID, and optionally the name or URL
User	The user ID	The ID, and optionally the name or URL
Select, Checkbox, Radio, Button Group	The option key	The key or the label, depending on Return Format
Date Picker	Ymd, for example 20260819	The date in your Return Format
Date Time Picker	Y-m-d H:i:s	The date and time in your Return Format
Time Picker	H:i:s	The time in your Return Format
True / False	1, or empty when unchecked	1 or 0

The date and time formats above are what ACF/SCF always saves, whatever display or Return Format you picked. So to filter for posts dated after August 19, 2026, compare a Date Picker against 20260819, not against 19/08/2026.

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

• Multi-value fields: a Checkbox, Gallery, Relationship, or a Select with Multiple stores its whole list as one serialized value. Comparisons against it are unreliable, so filter on something else.
• Repeater stores only its row count, and Flexible Content stores only the list of layout names used. Their actual content lives under separate keys.
• Sub-fields inside a Repeater, Group, Flexible Content, or Clone 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.
• Message, Accordion, Tab, and Separator fields store no value, so they produce no variables.
• Field groups shown on comments, widgets, or Blocks aren’t read.
• An attachment field group limited to certain file types is offered on every attachment, not only on files of that type. It resolves to an empty value where it doesn’t apply.
• Options pages that were changed to save their values somewhere other than the WordPress options table aren’t listed as options pages. Read those values from the post or user they’re saved on.