Using the ACF Datastore

Documentation Using the ACF Datastore

Last updated May 13, 2026

Overview

The ACF datastore is an opt-in feature that integrates ACF fields with Gutenberg’s native wp.data store. When enabled, ACF field values are saved through WordPress’s REST API instead of the legacy metabox AJAX request, enabling full revision and autosave support.

Note: The datastore is currently available in ACF PRO while we collect feedback from early adopters.

Requirements

• ACF PRO 6.8.1 or later
• WordPress 6.7 or later

Enabling the Datastore

The datastore is disabled by default. To enable it, add this filter to your theme or plugin:

add_filter( 'acf/settings/enable_datastore', '__return_true' );

You can also enable it conditionally:

add_filter( 'acf/settings/enable_datastore', function( $enabled ) {
    // Only enable for specific post types
    if ( get_post_type() === 'product' ) {
        return true;
    }
    return $enabled;
});

Features

Revision Support

When the datastore is enabled, ACF field values are included in post revisions. This means you can:

• View ACF field changes in the revision diff screen
• Restore ACF field values when reverting to a previous revision
• See exactly what changed between versions

Autosave Support

ACF field values are automatically captured in WordPress autosaves. If the browser crashes or the user navigates away, their ACF field data is preserved alongside the post content.

JavaScript API

The datastore exposes a wp.data store called acf/fields for reading and writing field values programmatically.

Reading Field Values

// Get a single field value
const value = wp.data.select( 'acf/fields' ).getFieldValue( 'field_name' );

// Get all field values
const allValues = wp.data.select( 'acf/fields' ).getFieldValues();

Writing Field Values

// Set a single field value
wp.data.dispatch( 'acf/fields' ).setFieldValue( 'field_name', 'new value' );

// Set multiple field values
wp.data.dispatch( 'acf/fields' ).setFieldValues({
    field_name: 'value',
    another_field: 'another value'
});

Subscribing to Changes

wp.data.subscribe( () => {
    const value = wp.data.select( 'acf/fields' ).getFieldValue( 'my_field' );
    console.log( 'Field value changed:', value );
});

Legacy API Compatibility

The datastore maintains bidirectional sync with ACF’s existing jQuery-based field DOM. This means:

• Changes made via the JavaScript API update the field inputs in the metabox
• Changes made by editing fields in the metabox update the datastore
• Existing code using acf.getField() continues to work

You can also use acf.store.set() to write values, which syncs to both the DOM and the wp.data store.

Relational Field Label Hydration

When you set a value programmatically on relational fields (post_object, page_link, relationship, taxonomy, user), the datastore automatically fetches the display label via AJAX if the target ID isn’t in the field’s pre-rendered options.

This also applies when restoring a revision that references posts or terms that weren’t in the original field choices.

Migration Considerations

Save Flow Changes

When the datastore is enabled, ACF fields are saved through Gutenberg’s REST API rather than the legacy metabox AJAX request. If you have custom JavaScript hooked into ACF’s save events through the metabox path, you’ll need to update it to hook into Gutenberg’s REST save instead.

Before (legacy save):

acf.addAction( 'submit', function( $form ) {
    // This won't fire with the datastore enabled
});

After (REST save):

wp.data.subscribe( () => {
    const isSaving = wp.data.select( 'core/editor' ).isSavingPost();
    // Handle save state
});

Existing Revision Handling

If you’ve built custom revision handling for ACF fields (using wp_save_post_revision or similar), you may see double-handling when the datastore is enabled since ACF values are now natively included in revisions.

Review any custom revision code and remove it if it’s now redundant.

Known Limitations

Nested Relational Fields

Relational sub-fields inside Repeaters or Groups are not covered by the AJAX label hydration in this release. Only top-level relational fields hydrate correctly when the value isn’t in the pre-rendered options.

Workarounds: – Keep relational fields at the top level where possible – Pre-populate the field’s choices on the server using the acf/fields/{field_type}/query filter – After setting a value programmatically, reload the page to let the field’s render path fetch the label

WordPress Version Requirement

The acf/settings/enable_datastore filter has no effect on WordPress versions before 6.7. The datastore requires APIs that were stabilized in that release.

Disabling the Datastore

If you encounter issues after enabling the datastore, you can disable it to immediately revert to the legacy save path:

add_filter( 'acf/settings/enable_datastore', '__return_false', 100 );

This returns ACF to exactly the same behavior as version 6.8.0 with no other code changes required.

Troubleshooting

Fields Not Saving

1. Verify WordPress 6.7+ is installed
2. Check that the filter is being applied (use acf_is_using_datastore() to verify)
3. Look for JavaScript errors in the browser console
4. Ensure no other plugins are interfering with the REST API save

Custom Save Hooks Not Firing

If your custom JavaScript save hooks stopped working, they’re likely hooked into the legacy metabox AJAX path. Update them to use Gutenberg’s wp.data subscriptions instead.

Revision Diff Shows Raw Data

ACF field values are stored in meta._acf for the datastore. The revision diff will show the serialized values. This is expected behavior.

Related

• Filters: acf/settings/enable_datastore
• Features: Abilities API Integration
• Features: WP REST API Integration
• Integrations: Block Bindings
• Field Types: User