ACF load_value Hook: Filter Values on Load [Guide]

ACF load_value() hook illustration: arrow loading a value into a tray

Sometimes the stored value is empty or not what the template needs. The ACF load_value filter lets you change the value right after ACF reads it, before any template receives it.

This guide covers the filter’s arguments, its name, key, and type variants, and a default value example.

Usage

<?php
add_filter( 'acf/load_value', 'my_load_value', 10, 3 );

function my_load_value( $value, $post_id, $field ) {
    return $value;
}

The callback receives three arguments:

  • $value is the value read from the database.
  • $post_id is the object the value belongs to, such as a post ID or 'user_5'.
  • $field is the field settings array, including name, key, and type.

Target a Single Field

Use a variant to run the filter for only some fields. The variant is part of the hook name:

  • acf/load_value/name=price matches the field by name.
  • acf/load_value/key=field_5f2a1b matches the field by key.
  • acf/load_value/type=number matches every field of one type.

Set a Default Value

This example returns 0 when a price field is empty, so the template never prints a blank number:

<?php
add_filter( 'acf/load_value/name=price', 'my_default_price', 10, 3 );

function my_default_price( $value, $post_id, $field ) {
    if ( '' === $value ) {
        return 0;
    }

    return $value;
}

Tip: load_value changes what ACF returns, but it doesn’t write to the database. Use acf/update_value when you need to change the stored data.

FAQs About ACF load_value

What Is the Difference Between load_value and format_value?

load_value runs when ACF reads the raw value from the database. format_value runs later, when the value is formatted for output.

Does load_value Change the Stored Data?

No. It changes the value ACF returns for that request. The database keeps the original data.

Why Does My Filter Not Run?

Check the hook name and the variant. A name or key variant runs only when it matches the field exactly.

Conclusion

The acf/load_value filter is the right place to set defaults and normalize values before a template uses them. Start with a name or key variant so the change touches only one field.

Related ACF guides:

Need a custom theme or ACF setup? Hire a WordPress developer, or reach out to me directly.

About The Author

Picture of Andriy Haydash

Andriy Haydash

Andriy Haydash is a WordPress Expert who helps people build and launch successful WordPress membership and e-learning websites.

Note: Not all of the articles are written directly by me.
Affiliate Disclaimer: Some links in the post may be my affiliate links

Kinsta - Managed Hosting for WordPress

Before YOU Leave...
Join My Newsletter

Get practical tips & tricks on how to start, grow and market your course/membership site.