Complete Guide: How to Use Advanced Custom Fields (ACF) Hooks

Published on: November 25, 2025Author: AlexComment: 0

Advanced Custom Fields (ACF) is a WordPress plugin that simplifies the creation and management of custom fields (text, selects, repeaters, galleries, flexible content, etc.) through a visual interface. It allows you to store structured data associated with posts, users, taxonomies, or options, and provides hooks (filters and actions) to intercept their lifecycle: loading, rendering, validation, saving, and formatting.

Main Hooks

Filters

Below is a list of ACF’s main filters with a short description of their usage.

acf/load_field (+ name=/key=/type=)

When: Before rendering the field in the admin.
Parameters: array $field
Returns: array $field
Uses: Modify label, placeholder, choices, wrapper.

acf/prepare_field (+ name=/key=/type=)

When: Before preparing the final field array.
Parameters: array $field
Returns: array $field
Uses: Modify final attributes, disable field.

acf/load_value (+ name=/key=/type=)

When: When loading the stored field value.
Parameters: $value, $post_id, array $field
Returns: $value
Uses: Format the value before displaying it.

acf/update_value (+ name=/key=/type=)

When: Before saving the field value.
Parameters: $value, $post_id, array $field
Returns: $value
Uses: Validate or sanitize values.

acf/validate_value (+ name=/key=/type=)

When: When validating a field value.
Parameters: $valid, $value, $field, $input
Returns: $valid
Uses: Enforce custom validation requirements.

acf/format_value (+ name=/key=/type=)

When: When formatting the value for frontend usage.
Parameters: $value, $post_id, array $field
Returns: $value
Uses: Adjust presentation for templates.

Actions

acf/save_post

When: After saving ACF fields.
Parameters: $post_id
Uses: Save extra info, sync external data.

acf/delete_value

When: When an ACF value is deleted.
Parameters: $post_id, $key
Uses: Remove additional related data.

acf/render_field

When: When rendering the field’s HTML.
Parameters: array $field
Uses: Add extra HTML or attributes.

acf/render_field_settings

When: When rendering field settings in the admin.
Parameters: array $field
Uses: Add custom options to a field type.

acf/input/admin_enqueue_scripts

When: When loading CSS/JS in admin for ACF fields.
Uses: Enqueue custom scripts or styles.

Practical Examples

Case 1:

Save an ACF field into the author’s user meta using acf/save_post

<?php
add_action( 'acf/save_post', 'saveAuthorMetaFromAcf' );
function saveAuthorMetaFromAcf( $postId ) {
    if ( isset( $_POST['acf'] ) && isset( $_POST['acf']['field_random_author_meta'] ) ) {
        $authorId   = get_post_field( 'post_author', $postId );
        $fieldValue = sanitize_text_field( $_POST['acf']['field_random_author_meta'] );

        update_user_meta( $authorId, 'custom_author_meta', $fieldValue );
    }
}

Case 2:

Modify all select fields using acf/load_field/type=select

<?php
add_filter( 'acf/load_field/type=select', 'modifySelectFields' );
function modifySelectFields( $field ) {
    $field['choices']['new_option'] = 'Extra Option';
    return $field;
}

Case 3:

Format a numeric value on frontend with acf/format_value

<?php
add_filter( 'acf/format_value/name=price_field', 'formatPriceValue', 10, 3 );
function formatPriceValue( $value, $postId, $field ) {
    return '$' . number_format( (float) $value, 2 );
}

Case 4:

Validate a required field using acf/validate_value

<?php
add_filter( 'acf/validate_value/name=document_id', 'validateDocumentId', 10, 4 );
function validateDocumentId( $valid, $value, $field, $input ) {
    if ( empty( $value ) ) {
        $valid = 'This field is required.';
    }
    return $valid;
}

Case 5:

Add a CSS class using acf/prepare_field

<?php
add_filter( 'acf/prepare_field/name=custom_title', 'addCustomClassToField' );
function addCustomClassToField( $field ) {
    $field['wrapper']['class'] .= ' highlight-title';
    return $field;
}

Case 6:

Sanitize a URL before saving using acf/update_value

<?php
add_filter( 'acf/update_value/name=website_url', 'sanitizeWebsiteBeforeSave', 10, 3 );
function sanitizeWebsiteBeforeSave( $value, $postId, $field ) {
    return esc_url_raw( $value );
}

Case 7:

Modify a Flexible Content field using acf/load_field/type=flexible_content

<?php
add_filter( 'acf/load_field/type=flexible_content', 'customFlexibleContentLabel' );
function customFlexibleContentLabel( $field ) {
    $field['label'] = 'Custom Flexible Blocks';
    return $field;
}

Case 8:

Repeater — process subfields when saving using acf/save_post

<?php
add_action( 'acf/save_post', 'handleRepeaterOnSave' );
function handleRepeaterOnSave( $postId ) {
    // repeater name: gallery_items
    if ( isset( $_POST['acf'] ) && isset( $_POST['acf']['field_gallery_items'] ) ) {
        $items = $_POST['acf']['field_gallery_items']; // array of rows

        // Example: save the number of rows as meta
        $count = is_array( $items ) ? count( $items ) : 0;
        update_post_meta( $postId, 'gallery_items_count', intval( $count ) );

        // Loop through rows and process subfields (e.g., image, caption)
        if ( is_array( $items ) ) {
            foreach ( $items as $index => $row ) {
                $caption = isset( $row['field_sub_caption'] )
                    ? sanitize_text_field( $row['field_sub_caption'] )
                    : '';

                // Save individual captions as separate meta entries
                update_post_meta( $postId, "gallery_item_{$index}_caption", $caption );
            }
        }
    }
}

This guide walked you through ACF’s main hooks, explained the difference between filters and actions, and demonstrated practical examples for modifying fields, validating, sanitizing, formatting, and working with complex field types like repeater and flexible content. Use these snippets as a foundation and adapt them to your actual field names or keys.