Add filter picking acf-json file path

• ascendjoe

• August 5, 2025 at 12:01 pm

Currently, if you add additional paths for ACF to load json from using acf/settings/load_json, it will use the LAST found acf field group. This means, even if a field is edited via the editor, it will still use the last path, such as from a plugin. This is described in the documentation:

This filter will allow plugin and theme developers to easily register field groups, post types, taxonomies, or options pages which cannot be edited by clients.

I have a different use case – we are an agency and want to have some base packages as all of our sites share a similar structure but I still need to be able to add fields to suit different clients, such as adding an additional image field in some nested field group.

Currently, there is no way to change the behavior of this, it always picks the last. I propose adding a filter that would enable plugin developers to choose which file should be used for a specific field group.

// Pick the newest version, regardless of if its in the theme or plugin folder
add_filter('acf/json/pick_file', function($currentFile, $newFile, $newJson, $loadPath) {
	// Only modify it if its the plugins path
	if($currentFile && $loadPath == plugin_dir_path( __FILE__ ) . 'acf-json') {
		$currentJson = json_decode( file_get_contents( $currentFile ), true );
		// Compare modified dates and take newest
		if ( $currentJson['modified'] < $newJson['modified'] ) {
			return $newFile;
		} else {
			return $currentFile;
		}
	}
	return $newFile;
});

All the code to support this would be very simple in the includes/local-json.php file:

// __construct()
add_filter( 'acf/json/pick_file', array( $this, 'pick_file' ), 10, 4 );

// scan_files() line 326
$json_files[ $json['key'] ] = apply_filters( 'acf/json/pick_file', $file, $json_files[ $json['key'] ] ?? null, $json );

// Maintain current behavior
public function pick_file( $currentFile, $newFile, $newJson, $path ) {
	return $newFile;
}

Right now, the best you can do is choose to not include the acf-folder when doing acf/settings/load_json. This is problematic though if there are multiple field groups you want to load. Being able to filter individual files would unlock a lot of possibilities.

TLDR Goal:

• Create new theme, importing packages via composer
• Use acf-json from packages
• Make changes via editor, save to themes acf-json folder
• Right now, will still use the packages acf-json, despite the theme’s being newer.
  • Would like to use the themes json file, while allowing sync from the package should we update it.

Workaround:
Prepend the package’s acf-folder path. This means the theme will always win, but it does unfortunately break the sync feature. Even if the package is modified and newer, it doesn’t show sync available.