Read an ACF block's fields before you fill it

ContentBeginner~5 min

Before you start

Advanced Custom Fields active with at least one ACF block registered, and plugin version 1.10.0 or newer. Both block type reads are off until you switch them on in the Abilities tab. The connected user needs the edit-posts capability. Nothing here writes.

ACF blocks are where a lot of custom sites keep their best layouts: a team member card, a testimonial slider, a pricing row with exactly the fields the client asked for. They are also easy for an agent to get wrong, because the data lives inside the block comment under field names nobody remembers, and a key ACF does not recognize is silently ignored.

This prompt reads the block’s own definition first. You get the field list and a working example before anyone writes a single value.

The prompt
I want to fill one of our ACF blocks, but first show me exactly what it
takes. Read only, change nothing.
List the block types on this site and pick out the ACF blocks. Then open
[the team member block] and give me a table of its fields: the field name
to use as a data key, its type, any choices it allows, and any sub-fields.
Show me the example block comment you get back for it, and tell me which
fields expect an attachment ID rather than a URL, and which only accept
one of a set of choices. Do not fill anything in yet.

Why this is safe to run

Both abilities are reads, so nothing on the site changes. The block type read returns the field names, types, choices and sub-fields ACF registered for that block, plus an example block comment that uses those names as its data keys, with image fields taking attachment IDs.

That example is what makes the next step reliable. Instead of guessing at keys, the agent copies the shape it was given and swaps in your values. When you have the values ready, fill an ACF block on a page picks up from here and writes one block, after you approve it.

Already connected? Skip the paste. Ask your agent for the “read an ACF block’s fields” recipe, or name the block you want to fill, and it runs the same reads on your own install.

How it works

  1. List the registered block types and keep the ones marked as ACF blocks.
  2. Open the ACF block you name and read its fields: name, type, choices and any sub-fields.
  3. Show the example block comment the plugin returns, which uses the field names as data keys.
  4. Note which fields need an attachment ID instead of a URL, and which only accept set choices.

Questions

How is this different from reading a post's ACF fields?
The ACF post field abilities read and write values stored on a post. An ACF block keeps its data inside the block itself, in the page content, so its fields are read from the block type definition instead.
What happens if the agent uses a wrong field name later?
ACF ignores data keys that match none of the block's fields. Since 1.10.0 a write that hits this returns an unknown_acf_field content warning listing the keys it ignored and the block's real field names.