Upgrade Guide – Version 4

Last updated Oct 5, 2017


The ACF plugin has undergone some major changes in version 4 to adhere to the new terms & conditions set by WordPress.

To make your upgrade a seamless operation, please read this guide before updating.


No changes have been made to any data stored in the database. Upgrading and downgrading is as easy as changing the plugin files!


Previously, all Add-ons were unlocked via an activation code (purchased from the ACF Add-ons store). New to v4, all Add-ons act as separate plugins which need to be individually downloaded, installed and updated.

You can find all purchased add-ons via your store account here: https://www.advancedcustomfields.com/my-account.

You may also download any previously activated add-ons from within the ACF plugin. After upgrading to v4, you will be redirected to the what’s new page where you can see and download v4 add-ons which were previously activated.

Custom Field Types

Creating your own field type has never been easier! Unfortunately, version 3 field types are not compatible with version 4. Migrating your field types is easy, please follow this tutorial to learn more.

You will find that some functions have changed names. I advise that you start with a blank dummy.php field file and copy across your old functions one by one into the new function spaces.

 Actions / Filters

Many of the actions & filters have changed. Please see the following table to find the appropriate changes.


Version 3 Version 4
acf_save_post acf/save_post
acf_head-input acf/input/admin_head
acf_print_styles-input acf/input/admin_enqueue_scripts
acf_print_scripts-input  acf/input/admin_enqueue_scripts
acf_head-fields acf/field_group/admin_head
acf_print_styles-fields acf/field_group/admin_enqueue_scripts
acf_print_scripts-fields acf/field_group/admin_enqueue_scripts


Version 3 Version 4
acf_load_field acf/load_field
acf_load_field-{$field_type} acf/load_field/type={$field_type}
acf_load_field-{$field_name} acf/load_field/name={$field_name}
acf_load_field-{$field_key} acf/load_field/key={$field_key}
acf_load_value  acf/load_value
 acf_load_value-{$field_type}  acf/load_value/type={$field_type}
 acf_load_value-{$field_name}  acf/load_value/name={$field_name}
 acf_load_value-{$field_key}  acf/load_value/key={$field_key}
 acf_update_value  acf/update_value
acf_update_value-{$field_type} acf/update_value/type={$field_type}
acf_update_value-{$field_name} acf/update_value/name={$field_name}
acf_update_value-{$field_key} acf/update_value/key={$field_key}
 acf_settings  acf/options_page/settings
acf_options_page_title [Removed]
acf_form_pre_save_post acf/pre_save_post

Options Page

Previously, the Options Page Add-on used 1 function and 2 hooks to modify it’s settings. These were:

  • function: register_options_page()
  • filter: acf_options_page_title
  • filter: acf_settings

Both the filters have been removed, however, the ‘register_options_page()’ function is still available and a new filter ‘acf/options_page/settings‘ can be used to customize the title, capability and sub pages.


This filter has been removed as it is no longer needed to hold activation codes or the options page settings. If you were previously using this filter to modify the soptions page’s settings, please use the new filter ‘acf/options_page/settings‘.


All previous API functions will continue to work in the exact same way. 3 new functions have been added! These are:

  • get_field_objects – mixture between get_fields and get_field_object
  • get_sub_field_object – mixture between get_sub_field and get_field_object
  • create_field – creates the HTML for a field
  • delete_field – deletes a field value from the DB