GT ACF Blocks Hooks Reference

Actions Used

WordPress Core Actions

plugins_loaded
Handler: acf_blocks_init()
Checks ACF availability and loads the plugin’s include files.

This ACF Blocks hooks reference covers both directions: the WordPress core actions the plugin hooks into (with priorities, so you can hook before or after it) and the filters it exposes for customizing block behavior without touching plugin files.

init (priority 5)
Handler: acf_blocks_register_styles()
Pre-registers all block stylesheets with wp_register_style() for conditional loading.

enqueue_block_editor_assets
Handler: acf_blocks_enqueue_editor_assets()
Enqueues the block transforms JavaScript in the editor.

enqueue_block_assets (priority 999999)
Handler: acf_blocks_enqueue_editor_styles()
Enqueues one consolidated, cacheable editor CSS bundle (admin only) and dequeues the per-block style handles in the editor. Uses a very high priority to ensure styles load after theme styles. Frontend requests keep conditional per-block loading.

send_headers (priority 100)
Handler: acf_blocks_send_server_timing()
Emits opt-in Server-Timing headers (bootstrap and registration timings) in debug environments. Gate it with the acf_blocks_server_timing_enabled filter.

admin_enqueue_scripts
Handler: acf_url_preview_admin_scripts()
Enqueues the URL Preview admin JavaScript on post/page edit screens.

wp_enqueue_scripts
Handler: acf_star_rating_register_assets()
Registers the star rating frontend script.

the_content (priority 10)
Handler: acf_toc_add_heading_ids()
Adds id attributes to headings that lack them (only when a TOC block is present in the post).

wp_footer (priority 100)
Handler: md_output_stored_block_css()
Outputs collected inline CSS from Section Block instances.

admin_menu (priority 99)
Handler: ACF_Blocks_License_Manager::add_submenu_page()
Adds the license management page under Settings.

admin_init
Handler: ACF_Blocks_License_Manager::handle_license_actions()
Processes license activation/deactivation form submissions.

admin_notices
Handler: ACF_Blocks_License_Manager::admin_notices()
Shows expired license notice on the Plugins screen.

ACF Actions

acf/init (priority 5)
Handler: acf_blocks_load_blocks()
Registers all blocks, field groups, and extra files from a generated, OPcache-friendly manifest. A filesystem scan of the blocks directory remains as a fallback when the manifest is missing. Blocks disabled through the Block Manager are skipped.

AJAX Actions

wp_ajax_acf_star_rating_submit and wp_ajax_nopriv_acf_star_rating_submit
Handler: acf_star_rating_handle_submission()
Backward-compatible admin-ajax path for star rating submissions. New submissions go through the acf-blocks/v1/ratings REST route, registered on rest_api_init.

wp_ajax_acf_url_preview_fetch
Handler: acf_url_preview_fetch_handler()
Fetches URL metadata for the URL Preview block.

wp_ajax_acf_url_preview_import_image
Handler: acf_url_preview_import_image_handler()
Imports an external image to the media library.

Cron Actions

acf_blocks_verify_license (weekly)
Handler: ACF_Blocks_License_Manager::verify_remote_license()
Checks license validity against the remote server.

acf_blocks_process_image_queue (single events)
Handler: acf_blocks_process_image_queue()
Processes the queued external-image downloads for the image localizer. Post saves only queue post IDs; this event does the downloading in the background.

acf_blocks_usage_scan_batch (single events)
Handler: acf_blocks_usage_scan_batch()
Runs the asynchronous block usage inventory scan started from the Performance & Block Manager card.

Filters Used

WordPress Core Filters

block_categories_all (priority 10)
Handler: acf_blocks_register_category()
Inserts the “ACF Blocks” category at the top of the block inserter.

render_block_data
Handler: acf_blocks_reconstruct_nested_repeaters()
Converts flat repeater keys to nested row-N format for the block editor (admin and REST requests only).

save_post (priority 20, action)
Handler: acf_blocks_queue_external_images()
Queues posts containing external images in ACF block data for background localization. The actual downloads run on the acf_blocks_process_image_queue cron event, not during the save request.

pre_set_site_transient_update_plugins
Handler: ACF_Blocks_License_Manager::check_for_update()
Checks for plugin updates when WordPress refreshes the update transient.

plugins_api (priority 10)
Handler: ACF_Blocks_License_Manager::plugin_info()
Provides plugin information for the update details modal.

delete_site_transient_update_plugins
Handler: ACF_Blocks_License_Manager::clear_update_transient()
Clears the cached update info when the update transient is deleted.

plugin_action_links_{basename}
Handler: ACF_Blocks_License_Manager::plugin_action_links()
Adds a “License” link to the plugin’s action links on the Plugins screen.

ACF Filters

acf/fields/relationship/query (priority 10)
Handler: acf_blocks_optimize_post_display_query()
Optimizes the relationship field query for the Post Display block.

acf/fields/relationship/query (priority 5)
Handler: acf_blocks_optimize_post_display_result()
Optimizes relationship field results for the Post Display block.

Custom Filters (Public API)

acf_blocks_is_local_image_url

Allows site owners to declare additional hostnames as “local” for the image localizer. When this filter returns true, images from that host will not be downloaded.

add_filter( 'acf_blocks_is_local_image_url', function( $is_local, $url_host, $site_bare ) {
    if ( $url_host === 'my-cdn.example.com' ) {
        return true;
    }
    return $is_local;
}, 10, 3 );

Parameters:

• $is_local (bool) – Current local status (false when this runs).
• $url_host (string) – The hostname of the image URL.
• $site_bare (string) – Your site’s hostname without www..

acf_blocks_template_path
Filters the absolute template directory for a block before registration. Receives $block_folder and $block_name. This is the override point for pointing a block’s render at your own file.

acf_blocks_register_args
Filters the args array passed to register_block_type() per block. Receives $args and $block_name.

acf_blocks_disabled_blocks
Filters the list of block names disabled through the Block Manager. Lets you disable blocks in code instead of (or on top of) the settings screen.

acf_blocks_recovery_innerblock_names
Filters the set of block names the block recovery helper treats as InnerBlocks blocks when re-wrapping orphaned inner HTML.

acf_blocks_server_timing_enabled
Enables or disables the Server-Timing metrics header. Defaults to the value of WP_DEBUG.

Quick answers to common questions: