Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared hosting Managed WordPress Cloud hosting VPS hosting By reader location Hosting finder
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Blog Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Developer · Guide

WordPress Hooks Explained: Actions vs Filters

WordPress Hooks Explained: Actions vs Filters

Short answer

WordPress hooks let your code run at set points without editing core files. Actions do a task and return nothing, while filters take a value, change it, and return it. Register actions with add_action() and filters with add_filter(), passing the hook name and your callback function.

Key takeaways

  • A hook is a named point where your code can run without editing core files.
  • Actions do a task and return nothing, while filters change a value and return it.
  • add_action() and add_filter() take the hook name, a callback, a priority, and an argument count.
  • The default priority is 10, and lower numbers run earlier.
  • A filter must return a value in every path, or the filtered value is lost.
  • Custom hooks use do_action() and apply_filters(), with names prefixed by your plugin slug.

What is a WordPress hook?

A hook is a named point in WordPress where your code can run, so you can change behavior without editing core files.

Developer.WordPress.org states that hooks are a way for one piece of code to interact with or modify another piece of code at set, pre-defined spots (checked November 2026).

The same page states that hooks make up the foundation for how plugins and themes interact with WordPress core, and that core itself uses them at many points (checked November 2026).

You write a callback function, then register it with a hook. WordPress calls your function when it reaches that point in its run.

A guide on how to create a WordPress plugin shows the plugin file where hook code usually lives.

What is the difference between actions and filters?

Actions do something at a point in the run and return nothing, while filters change a value and return the changed value.

Developer.WordPress.org states that actions allow you to add data or change how WordPress operates, and that an action callback does not return anything back to the calling hook (checked November 2026).

The same page states that filters give you the ability to change data during the run of WordPress core, plugins, and themes, and that a filter callback accepts a variable, modifies it, and returns it (checked November 2026).

A short summary from the handbook puts it plainly: an action acts on something and then exits, while a filter takes the value it receives, modifies it, and passes it back (checked November 2026).

Use an action to send an email, save a record, or print output. Use a filter to change a title, a piece of content, or a list of classes.

A guide on theme vs plugin in WordPress explains where hook code belongs, so it keeps working when the theme changes.

What do you need before you start?

You need a WordPress site you can edit, a code editor, and a plugin file or child theme file to hold your code.

Work on a staging copy first when the site is live. A hook with a wrong priority or a missing return can change every page, so check it away from visitors.

Pick a unique prefix for your functions and hook names, such as mysite_. A prefix stops your code from clashing with a function or hook from another plugin.

Know the hook name before you write the callback. The Plugin Handbook lists the core hooks, and each function reference page names the hooks it fires.

Check the PHP version your site runs. WordPress.org states that WordPress recommends PHP 8.3 or greater, and that WordPress still works with PHP 7.4 and later in older setups (checked November 2026).

Keep a list of the hooks you use and what each one does. That list makes the code easy to review later, and it helps the next person who reads it.

How do you add an action with add_action?

Register an action with add_action(), passing the hook name and the name of your callback function.

Developer.WordPress.org states that the process of adding an action has two steps: create a callback function, then add it to a hook with add_action() (checked November 2026).

The same page states that add_action() takes the hook name and the callback, and can also take a priority and a count of accepted arguments (checked November 2026).

A basic example runs a function when a post is saved:

function mysite_notify_on_save( $post_id ) {
    // Send a notice or update a record here.
}
add_action( 'save_post', 'mysite_notify_on_save' );

The callback receives the arguments the hook passes. For save_post, the first argument is the post ID, so your function should accept it.

The callback can be a function name, a class method, or a closure. PHP.net states that a callable is a reference to a function or method that is passed to another function as an argument (checked November 2026).

An action callback should not return a value for WordPress to use. Its job is to do the work, such as writing to the database or sending a message, and then finish.

A guide on how to fix a plugin conflict helps when two plugins hook into the same point and clash.

How do you add a filter with add_filter?

Register a filter with add_filter(), passing the hook name and a callback that takes a value, changes it, and returns it.

Developer.WordPress.org states that adding a filter has two steps: create a callback function, then add it to a hook with add_filter() (checked November 2026).

The same page states that add_filter() takes at least the hook name and the callback, and can also take a priority and a count of accepted arguments (checked November 2026).

A filter on the post title looks like this:

function mysite_filter_title( $title ) {
    return 'The ' . $title . ' was filtered';
}
add_filter( 'the_title', 'mysite_filter_title' );

The callback must return a value in every path through the code. A filter that forgets to return will pass an empty value on, and the title will vanish from the page.

Filters should work in isolation. Developer.WordPress.org states that filters should never have side effects such as affecting global variables and output (checked November 2026).

That means a filter should not print text or write to the database. It should take the value, change it, and return it.

How do priority and accepted arguments work?

Priority sets the order callbacks run in, and accepted arguments sets how many values your callback receives.

Developer.WordPress.org states that lower priority numbers run earlier, and that functions with the same priority run in the order they were added (checked November 2026).

The same page states that the default priority is 10, and that the default count of accepted arguments is 1 (checked November 2026).

Set a lower number to run before the default callbacks. Set a higher number to run after them, for example when your code must see a value another plugin already changed.

add_filter( 'the_content', 'mysite_add_note', 20, 1 );

This call runs at priority 20, so it runs after callbacks at priority 10. The last number, 1, says the callback accepts one argument.

If the hook passes more than one argument and you need them, raise the count. Developer.WordPress.org states that a callback can accept from none up to the total number of arguments passed in the matching apply_filters() call (checked November 2026).

A common mistake is to write a callback that takes two arguments but leave the count at 1. WordPress will then pass only the first argument, and the second will be empty.

Which core hooks should you learn first?

Learn init, wp_enqueue_scripts, save_post, the_content, and wp_head, because they cover the most common jobs.

init fires after WordPress has loaded and before any output. Register post types and taxonomies on init, so they exist before queries run.

A guide on how to create a custom post type in WordPress uses init to register the post type at the right point.

wp_enqueue_scripts is the hook for loading CSS and JavaScript on the front end. Use it instead of printing script tags by hand, so WordPress can order and de-duplicate files.

save_post fires when a post is saved. Use it to update related data, clear a cache key, or send a notice tied to that post.

the_content is a filter on the post content before it is shown. Use it to add a note or a link to the end of a post without editing the template.

wp_head is an action in the head of the page. Use it to add meta tags or small bits of output that belong in the head.

HookTypeCommon use
initActionRegister post types and taxonomies
wp_enqueue_scriptsActionLoad CSS and JavaScript files
save_postActionReact when a post is saved
the_contentFilterChange post content before display
wp_headActionAdd output to the page head
body_classFilterAdd CSS classes to the body tag

How do you create your own custom hook?

Create a custom hook with do_action() for an action or apply_filters() for a filter, so other developers can extend your plugin.

Developer.WordPress.org states that custom hooks are created and called in the same way as WordPress core hooks, with do_action() for actions and apply_filters() for filters (checked November 2026).

Place the call where the extension point belongs. An action call marks a moment, such as after a settings form, and a filter call marks a value that others may change.

do_action( 'mysite_after_settings_page_html' );

Another plugin can then hook into that point:

add_action( 'mysite_after_settings_page_html', 'other_add_settings' );

Developer.WordPress.org states that because this is an action, no value is returned, and that with no priority given it will run at the default priority of 10 (checked November 2026).

For a filter, pass the value through apply_filters() and use the result:

$args = apply_filters( 'mysite_post_type_params', $args );

Prefix every custom hook name with your plugin slug. Developer.WordPress.org states that naming conflicts occur when two developers use the same hook name for different purposes, and that a prefix avoids those hard-to-find bugs (checked November 2026).

Learn WordPress states that custom hooks let you create either custom action hooks or custom filter hooks through your plugin code, so other developers can extend what your plugin does (checked November 2026).

A guide on how to create a custom REST API endpoint in WordPress shows another place where custom hooks let other code extend your work.

How do you remove a hook?

Remove a hook with remove_action() or remove_filter(), passing the same hook name, callback, and priority used when it was added.

The priority must match exactly. A callback added at priority 20 will not be removed by a call that omits the priority, because the default is 10.

remove_filter( 'the_content', 'mysite_add_note', 20 );

Remove a hook only when you have a clear reason, such as replacing a plugin feature with your own version. Removing a core hook can break a feature that depends on it.

Check that the removal runs after the hook was added. If your removal code runs too early, the callback is not yet registered, and the removal does nothing.

Use has_action() or has_filter() to check whether a callback is registered before you try to remove it. Those functions return the priority of the callback, or false when it is not registered.

What mistakes should you avoid?

Avoid forgetting the return in a filter, echoing from a filter, and using generic names that clash with other code.

A filter without a return is the most common hook bug. The value passed in is lost, and the page shows an empty title, empty content, or a broken list.

Echoing from a filter is almost as common. A filter runs while WordPress is building a value, so printed output lands in the wrong place on the page. Put output in an action instead.

Generic function names clash. A function named add_note may already exist in another plugin, and PHP will stop with a fatal error when it loads the second one. Prefix every function with your plugin slug.

Do not hook a heavy task to a hook that fires on every page load. A slow API call on init will slow every page, including pages that never use the result.

Do not use a hook name that another plugin already uses for a different purpose. Developer.WordPress.org states that you should always use unique names for each hook, and never create an action and a filter with the same name (checked November 2026).

A guide on how to check a plugin for vulnerabilities covers how to review hook code before you trust it on a live site.

How do you check that a hook works?

Check that the callback runs, that it runs at the right time, and that the page still shows the value you expect.

Add a short log line inside the callback while you check, then remove it. Load the page and confirm the log entry appears once, not twice and not never.

For a filter, view the page and confirm the changed value shows where it should. For an action, confirm the side effect, such as the saved record or the sent notice, actually happened.

If the callback never runs, check three things: the hook name is spelled right, the file with the code is loaded, and the priority matches when you try to remove it.

If the callback runs twice, check that you did not register it twice. A file loaded two times, or a hook added in two places, will double the effect.

If the page breaks, remove the hook code and load the page again. When the page works without it, add the code back one piece at a time until the bad line shows up.

Frequently asked questions

Can a filter callback return nothing?

No. A filter must return a value, even if it returns the value unchanged. If a filter callback returns nothing, the value passed to the next step is empty, and the title, content, or list it was filtering will vanish from the page.

Can an action and a filter share the same name?

Yes. Actions and filters are the same system under the hood, and WordPress does not stop you from using one name for both. The handbook advises against it, because a shared name makes the code hard to read and easy to break by mistake.

Why does my hook callback never run?

Check that the hook name is spelled right, that the file holding the code is loaded, and that the hook has already fired by the time your code runs. A callback added after its hook fired will wait until the next time that hook runs.

Can I create my own hooks in a plugin?

Yes, with do_action() for actions and apply_filters() for filters. Prefix the hook name with your plugin slug so it cannot clash with a hook from another plugin, and document what the hook passes and what it expects back.

Do hooks work in JavaScript as well as PHP?

Yes. In JavaScript, the @wordpress/hooks package offers addAction() and addFilter() through the wp.hooks object. The main difference is that the JavaScript versions also need a namespace as the second argument, in the form vendor/plugin/function.

How does hook priority decide the run order?

Lower numbers run first, and the default is 10. A callback at priority 9 runs before one at 10, and a callback at 20 runs after both. Callbacks at the same priority run in the order they were added.

Sources

  1. Hooks WordPress Developer Resources
  2. Actions WordPress Developer Resources
  3. Filters WordPress Developer Resources
  4. Custom Hooks WordPress Developer Resources
  5. add_filter() WordPress Developer Resources
  6. add_action() WordPress Developer Resources
  7. Custom hooks Learn WordPress
  8. Requirements WordPress.org

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

Written and checked byWPLegible Editorial Team Independent WordPress reviews and guides

Researched from the primary sources listed above and checked against our editorial rules before publishing.