Add ACF Local JSON to Your WordPress Theme

ACF Local JSON stores your Advanced Custom Fields field groups as JSON files inside your theme, so you can keep them in version control and move them between sites (why ACF field groups belong in Git explains how that fits a custom theme). When an acf-json folder exists in the active theme, ACF writes a JSON file there each time you save a field group and loads field groups from it.

The acf/settings/load_json filter controls where ACF looks for those files. Add the snippet to your theme’s functions.php, preferably in a child theme.

add_filter('acf/settings/load_json', 'my_acf_json_load_point');
function my_acf_json_load_point( $paths ) {
    // remove original path (optional)
    unset($paths[0]);
    // append path
    $paths[] = get_stylesheet_directory() . '/acf-json';
    // return
    return $paths;
}

How the ACF Local JSON filter works

• $paths is the list of folders ACF loads JSON from. unset($paths[0]) removes the default location; leave that line out if you want ACF to read both folders.
• $paths[] adds your own folder. Change /acf-json to load from a different folder.
• This filter only changes where ACF loads from. Where it saves JSON files is set separately with the acf/settings/save_json filter; ACF’s Local JSON documentation covers both.

ACF reads these files from the server’s disk, so each entry must be a folder path. That’s why the snippet uses get_stylesheet_directory(), which returns the theme’s path. get_stylesheet_directory_uri() returns the theme’s URL instead, and ACF can’t read files from a URL. Both functions point to the child theme when one is active; child and parent theme paths in WordPress compares them with the get_template_directory() versions.

Protect the acf-json folder

Add an index.php file inside the acf-json folder for security. It can be empty (WordPress uses a single // Silence is golden. comment in its own folders). If the server allows directory listing, it stops visitors from seeing the list of JSON files when they open the folder’s URL.

The folder must also be writable by the web server, or ACF can’t save JSON files into it.

Related articles

• a scalable WordPress theme structure: where the acf-json folder sits alongside templates and parts