An ACF Pro Addon – Component Field


Build it once, use it forever. A simple acf add-on that allows you to treat a field group as a component and reuse it in any other field groups.


  • WordPress 4+
  • ACF PRO 5.2.9+


  1. Login to your wordpress dashboard and navigate to Plugins > Add New.
  2. Click the Upload Plugin button beside the heading.
  3. Upload to the file upload area.
  4. Activate the plugin and have fun

When should I use this?

Have you ever found yourself creating the same set of fields in your project, say like, a custom lists menu, a testimonial block, sliders, or even a button? Well, this plugin might just be the one you need. Essentially, this plugin will allow you to only create that “same set of fields” once, and you can reuse it as many times as you want. Even better, if you want to add a new field in those “same set of fields” in the future, you only need to do it once, and it’ll apply to all the places you use it. See this example for details.

The concept – a reusable field

The concept is coming for the popular javascript library, React. A web page is really just built by a bunch of components and each component is independent. So, why can’t ACF be like that? A field group is built by different reusable components, each component has its own set of fields that should not be affect by another. You can put a component inside another component and inside another one. When you want to change something, you only need to change it once, and it’ll apply to all.

How it works?

When I started making this, I tried many different ways, but they all get stuck with the same problem: the values will get overwritten if you have more than 1. So, I took a step back and tried to find a way that won’t cause this issue. And it turned out, it already exists, the repeater field! The way repeater field works is, the sub_field’s key is combined with the parent field’s key with an index, like so, {parent_key}_{index}_{sub_field_key}. This way, when the value is save, the key is always different, and that’s why we can have a repeater field inside a repeater field.

The component field plugin is using the same logic, it’s treated as a repeater field, the values are consider sub_fields. By extending the functionality of the repeater field, we can also leverage the already built in functions. There’s no extra function you need to learn, no extra way of outputting the data. Everything is exactly the same as if you were using regular repeater field. See example for detail.

Why don’t give acf 4 a little love?

One reason is because, repeater doesn’t come free with acf 4, so this component field will need to rely on another paid plugin, I don’t feel comfortable about that. But the main reason is, the way acf 4 saves the fields and the way js is triggered in the backend. It’s not dynamic enough for us to swap the sub fields easily. If you are still using acf 4, you should really give acf 5 a try. I bet you’d love it and will never want to go back to acf 4.

The potentials

When you get a hang of it. You can prepare a list of components that you use commonly and export them to json files. Whenever you start a new project and you need the exact same component, you just need to import the component you already had, and modify it to suit your need, and you are good to go. Kinda like a DIY acf field without actually creating a full plugin. It also makes the complex field group extremely easy, as long as you are able to identify what should be a component and what’s not.

How to

Live Examples


  1. When you doing nested components, make sure you don’t go crazy and create an infinite loop.
  2. If you are using acf’s local cache json file, make sure you sync it before editing the component fields, because sometimes (happens once a while), it’d be out of sync, and the saved value will be lost.
  3. When you have tabs in your component group, when including that component, make sure you use the “block” layout (which is default already). Otherwise the layout will go off.
  4. Depending on the server’s setting, if you nest too many component (like, a lot), you might hit the max_post_size or max_input_nesting_level limit.
  5. An unknown bug or a bug that has not been fixed might destroys your data. I’ve already tested most of the extreme cases, but might still have missed one or two. If you are doing something crazily complex, please backup your database first. If you lost your data by using this plugin irregularly, an unknown bug or a bug that has not been fixed might destroys your data, I do not take responsibility for it. If you want to go crazy with this plugin, use with caution.


Test Log

Tested up to version:
Wordpress 4.5.2
WMPL 3.3.8



Component field’s “this is a component” checkbox will now remain checked upon duplication.
– Fix wpml language duplication not selecting the proper component group. After language duplication, it’ll “try” to find the matching translated component field.
– Added /lang/acf-component_field-default.pot file  


Add optional alternative styling for nested components. Huh?


-Fix php warning error when importing regular acf json file.


– Fix a copy-paste mistake that’ll cause warning error if wp_debug is on.


– Added plugin activation hook to fix component field not restore after updating plugin.


– Fix a bug where after updating a component field, acf_get_field_groups() doesn’t check the local json cache syncing properly.
– Fix a bug where single sync/bulk sync from local json cache doesn’t set the proper status.


– Add ability to read local php fields generated by “acf_add_local_field_group()” in the “select field group” dropdown.
– Fix a bug where if a component field is exported to a local php export, it cannot render the sub fields..


– Added German translation, thanks to Thomas. Added index.php to prevent directory listing.


– Updated plugin metadata to point to the live demo


– Fix backend javascript when having nested component field


– Fix a frontend value parsing issue.


– Initial release.