How to Rename an ACF Flexible Content Subfield Safely
A Flexible Content subfield uses a row-indexed postmeta key such as sections_0_heading. The layout name does not appear in that key. Rename the child by migrating each matching value/reference pair to the new suffix, verifying the copies, and then changing the child definition. Leave the parent Flexible Content field and its serialized layout sequence unchanged. Field Renamer 0.2.0 supports eligible value-bearing Flexible Content subfields.
Separate the subfield from the layout
A Flexible Content field has three names in play: the parent field, the selected layout, and each child field inside that layout. This guide covers a child such as heading. A layout-name rename changes the parent sequence and needs a different workflow.
Inspect the saved metadata
The parent sections row stores an ordered array of layout names. Child values use the parent name, numeric row index, and child name. ACF stores the child field key in the matching underscore row.
sections a:2:{i:0;s:4:"hero";i:1;s:5:"quote";}
_sections field_sections
sections_0_heading Welcome
_sections_0_heading field_headingThe word hero is absent from sections_0_heading. Filter the parent sequence when you need the layout context, and use the child field key to prove ownership.
Scan every matching row instance
Anchor the metadata path at both ends and match the underscore reference to the selected child field key. Count row instances separately from posts because one post can contain the field several times.
^sections_[0-9]+_heading$
^_sections_[0-9]+_heading$Run the copy-first migration
After backup confirmation, Field Renamer snapshots each row, copies it to the new child-name suffix, verifies the raw value, and changes the definition. The parent layout order stays intact. Original child rows remain available for rollback until cleanup.
Update template calls
Replace get_sub_field('heading') with the new child name. Check layout partials, render callbacks, REST transforms, block templates, and imports. Calls to get_row_layout() remain unchanged because the layout name did not change.
Test more than one layout position
Verify posts where the target layout appears first, later, and more than once. Edit a migrated value, reorder the layouts, save, and reload before you consider cleanup.
Use the dedicated layout guide if you need to rename hero or quote rather than a child inside those layouts. Rename a Flexible Content layout →
Common questions
Does the Flexible Content layout name appear in the subfield meta key?+
No. Child metadata uses the parent field name, row index, and child name. The parent value stores the ordered layout-name sequence.
Can I rename a Flexible Content subfield with SQL?+
A carefully anchored update can move matching keys, but it does not prove child field-key ownership, retain snapshots, or coordinate the definition cutover.
Does the parent layout order change?+
No. A subfield rename leaves the serialized parent sequence unchanged.
Can I rename the Flexible Content container?+
No. Version 0.2.0 blocks container names because the parent name prefixes every descendant metadata path.