WordPress Hooks Explained: Actions vs Filters (With Real Examples)

Hooks are how WordPress lets you change what a theme or plugin does without touching its files. Here’s how actions and filters work, with copy-ready examples, priorities, arguments and the mistakes to avoid.

Every time WordPress loads a page, it pauses at hundreds of named points and asks: does anyone want to do something here? Those named points are hooks. They are the reason you can change how WordPress, a theme or a plugin behaves without editing a single one of its files, and the reason those changes survive updates.

This guide explains the two kinds of hooks, how to use them, and the handful of details (priority, arguments, timing) that trip most people up.

Key takeaways

  • Actions let you run code at a specific moment. Filters let you change a value before it is used.
  • You listen with add_action() / add_filter(); WordPress and plugins fire hooks with do_action() / apply_filters().
  • A filter callback must always return a value.
  • Put your hook code in a child theme, a code-snippets plugin or a small custom plugin, never in the plugin you are changing.

What is a hook in WordPress?

A hook is a named spot in the code where other code is allowed to join in. WordPress core has hundreds of them (init, wp_head, save_post, the_content…), and most well-built plugins add their own. WooCommerce alone fires more than 2,800 different hooks, and you can see every one of them in our WooCommerce hooks reference.

There are two kinds, and the difference is simple:

  • Action: “something is happening now”. You attach a function that does something: send an email, print some HTML, save extra data.
  • Filter: “here is a value, do you want to change it?” You attach a function that receives the value, changes it if needed, and hands it back.

How actions work

Somewhere in WordPress or a plugin there is a line like do_action( 'wp_footer' ). When PHP reaches it, every function attached to wp_footer runs. You attach one with add_action():

functions.php
// Print a small notice at the bottom of every page.
add_action( 'wp_footer', function () {
	echo '<p class="site-note">Thanks for visiting!</p>';
} );

Actions often pass data to your function. save_post, for example, passes the post ID, the post object and whether it is an update:

functions.php
add_action( 'save_post', 'myprefix_after_save', 20, 3 );

function myprefix_after_save( $post_id, $post, $update ) {
	// Ignore autosaves and revisions.
	if ( wp_is_post_revision( $post_id ) || wp_is_post_autosave( $post_id ) ) {
		return;
	}
	// Your code: clear a cache, notify a service, save extra data…
}

How filters work

A filter looks like $length = apply_filters( 'excerpt_length', 55 ). WordPress passes the value (55) through every attached function and uses whatever comes out the other end. That is why a filter must always return something: if your function returns nothing, the value becomes null and things break in confusing ways.

functions.php
// Make automatic excerpts 30 words long instead of 55.
add_filter( 'excerpt_length', function ( $length ) {
	return 30;
} );

// Add a reading hint after post content, but only on single posts.
add_filter( 'the_content', function ( $content ) {
	if ( is_single() && in_the_loop() && is_main_query() ) {
		$content .= '<p class="hint">Found this useful? Share it.</p>';
	}
	return $content; // Always return the value.
} );

Priority and accepted arguments

Both add_action() and add_filter() take two optional numbers after the callback:

  • Priority (default 10): lower numbers run earlier. If your change is being overwritten by another plugin, try a later priority such as 20 or 99.
  • Accepted arguments (default 1): how many values your function receives. If a hook passes three values and you want all three, you must say 3, as in the save_post example above. Forgetting this is the most common reason for “too few arguments” errors.

Every entry in our hooks references shows the arguments a hook passes, and the Example button writes the correct add_action/add_filter call, with the right argument count, for you.

Removing a hook

You can detach a function that WordPress, a theme or a plugin added, as long as you pass the same callback and the same priority it was added with:

functions.php
// Stop WordPress printing its version number in the page head.
remove_action( 'wp_head', 'wp_generator' );

// Plugins often add hooks late, so remove theirs after plugins have loaded.
add_action( 'plugins_loaded', function () {
	remove_action( 'wp_footer', 'some_plugin_footer_badge', 20 );
} );

Callbacks added as anonymous functions (closures) cannot be removed this way, which is one reason to use named functions in code that others may want to adjust.

Dynamic hook names

Some hook names are built while the code runs. WordPress core fires save_post_{$post->post_type}, so saving a page fires save_post_page and saving a product fires save_post_product. Plugins do the same: WooCommerce fires woocommerce_settings_api_form_fields_{$this->id} for each payment or shipping method. In our references these parts are shown in {braces}; replace them with the real value when you add your callback:

functions.php
// Runs only when a "page" is saved, not posts or products.
add_action( 'save_post_page', function ( $post_id ) {
	// …
} );

Creating your own hooks

If you write a plugin or theme, adding hooks makes it extendable by others, and by future you:

my-plugin.php
// Let others run code before your form renders.
do_action( 'myprefix_before_form', $form_id );

// Let others change the button label.
$label = apply_filters( 'myprefix_button_label', __( 'Send', 'myprefix' ), $form_id );

Prefix your hook names (myprefix_) so they never collide with another plugin.

Where to put your hook code

  • A code-snippets plugin: easiest for a few small tweaks, and it can disable a snippet that causes an error.
  • A child theme’s functions.php: fine for changes tied to the design. Note they stop working if you switch themes.
  • A small custom plugin or must-use plugin: best for anything important; it keeps working whatever theme you use. See how to customize a plugin without editing it.

Never put your code inside the plugin you are customizing. The next update replaces its files and your change disappears.

Common mistakes

  • Forgetting return in a filter, which wipes out the value.
  • Wrong argument count: using a second argument without setting accepted args to 2.
  • Hooking too late: adding an action after it has already fired (for example adding an init callback from inside a template file). Register hooks early, in functions.php or your plugin’s main file.
  • Echoing in a filter: filters should return content, not print it.
  • Running heavy code on every request: check conditions (is_admin(), is_singular()…) at the top of your callback and leave early when it doesn’t apply.

Finding the hooks a plugin offers

The hard part is usually not writing the callback but knowing which hook exists. We read the source code of thousands of popular plugins and list every action and filter, with the file, line, arguments and a ready-to-paste example. Search the plugin directory, open a plugin and choose Hooks, or read our guide on finding the right hook in any plugin.

FAQ

Do hooks slow down WordPress?

Attaching a function to a hook costs almost nothing. What matters is what your function does: a database query or remote request on every page load will be noticed, a simple check will not.

What is the difference between a hook and a shortcode?

A shortcode is something an editor types into content () to insert output in that spot. A hook runs code at a point in the page lifecycle, whether or not any content mentions it.

My hook code does nothing. What should I check?

Check that the hook name is spelled exactly right, that it actually fires on the page you’re testing (the Query Monitor method shows this), that your code is registered before the hook fires, and that another callback with a later priority isn’t overriding your change.

Leave a Reply

Your email address will not be published. Required fields are marked *