If there’s one concept that unlocks WordPress development, it’s hooks. Every plugin you’ve ever installed relies on them. Almost every customisation request I handle, from changing a WooCommerce checkout field to adding tracking code or altering search results, comes down to finding the right hook and attaching a small function to it.
Yet hooks confuse a lot of people, including developers who’ve been copying snippets for years. What’s the difference between an action and a filter? Why does a snippet work in one place but not another? Why can’t you remove a hook a plugin added?
Let’s clear it up properly.
The basic idea
WordPress runs through a long sequence of steps every time a page loads: loading plugins, setting up the theme, querying content, building the page and sending it to the browser. At many points along the way, WordPress pauses and says, in effect, “Does anyone want to do something here?” or “Does anyone want to change this value before I use it?”
Those pause points are hooks. Your code can attach a function to a hook, and WordPress will run your function at that moment.
There are two kinds:
- Actions let you do something at a specific point. Send an email when a post is published, add a script to the page, register a post type.
- Filters let you change something. Modify a title, change an excerpt’s length, alter a query, edit the content before it’s displayed.
The simplest way to remember the difference: actions do, filters change and return.
Actions
You attach a function to an action with add_action:
When WordPress reaches the wp_footer hook, near the end of the page, it runs mysite_add_footer_note, which outputs the paragraph.
Actions don’t need to return anything. They perform a task: output something, save something, send something.
Some actions you’ll use constantly:
- init: WordPress has loaded; register post types, taxonomies and shortcodes here.
- wp_enqueue_scripts: enqueue front-end scripts and styles.
- admin_enqueue_scripts: enqueue admin scripts and styles.
- save_post: runs when a post is saved.
- wp_head and wp_footer: add output to the page head or footer.
- template_redirect: runs before the template loads, useful for redirects.
- rest_api_init: register custom REST API routes.
Filters
Filters receive a value, let you modify it and expect you to return it:
WordPress passes the current excerpt length into your function. You return a new value, and WordPress uses it.
The most important rule with filters: always return a value. If your filter function doesn’t return anything, the value becomes null, and whatever WordPress was filtering disappears. I’ve seen entire page contents vanish because a filter on the_content forgot to return.
Common filters include:
- the_content: modify post content before display.
- the_title: modify titles.
- body_class: add classes to the body element.
- upload_mimes: change which file types can be uploaded.
- wp_mail_from and wp_mail_from_name: change the sender of WordPress emails.
- woocommerce_checkout_fields: modify WooCommerce checkout fields.
Filters should generally not output anything or cause side effects. Their job is to transform a value and return it.
Priority
Many functions can be attached to the same hook. Priority controls the order they run in. The default is 10. Lower numbers run earlier, higher numbers later.
Priority matters when:
- You need to run after a plugin has done its work, for example dequeuing a plugin’s script after the plugin enqueues it. Use a higher priority.
- You need to modify a value before other filters see it. Use a lower priority.
- Two filters conflict, and the last one wins.
If a snippet doesn’t seem to work, a priority problem is often the reason. Another function may be overriding your change later.
Accepted arguments
Many hooks pass more than one value. By default, your function receives only the first. To receive more, specify the number of accepted arguments:
| if ( wp_is_post_revision( $post_id ) | 'product' !== $post->post_type ) { |
|---|
The fourth parameter, 3, tells WordPress to pass three arguments. Without it, $post and $update would be missing, and PHP would throw an error about too few arguments.
The documentation for each hook, in the WordPress Developer Resources, lists the arguments it passes.
Where to put hook code
Hook code needs to load before the hook fires. Common places are:
- A custom plugin: the best place for functionality that should survive theme changes.
- A must-use plugin in wp-content/mu-plugins: loads automatically, can’t be deactivated from the dashboard, good for essential site functionality.
- The theme’s functions.php: appropriate for presentation-related code tied to that theme.
Code snippet plugins are convenient for small changes, but code in files under version control is easier to review and maintain.
Timing problems
Hooks fire in a specific order during each request. If you try to attach to a hook that has already fired, nothing happens. If you call a function before WordPress has loaded what it depends on, you get errors.
For example, calling is_user_logged_in directly in a plugin file, outside a hook, may fail because user data isn’t loaded yet. Wrapping the code in a function attached to init or later fixes it.
A rough order of key hooks on a front-end request:
- plugins_loaded
- after_setup_theme
- init
- wp_loaded
- parse_request
- wp
- template_redirect
- wp_enqueue_scripts and wp_head, during template rendering
- wp_footer
- shutdown
Knowing this order helps you choose the right hook and avoid timing bugs.
Removing hooks
Sometimes you need to undo something a plugin or theme does. remove_action and remove_filter detach functions from hooks:
Removal has strict requirements:
- Same hook, same function, same priority. If the function was added with priority 20, you must remove it with priority 20.
- Removal must happen after the function was added. If you try to remove it before the plugin adds it, there’s nothing to remove yet. Wrap removal in a later hook, like init or wp_loaded, or use a priority that runs after.
Removing class methods
Plugins often attach methods of an object:
To remove it, you need a reference to the same object instance. Well-built plugins provide a way to access their main instance, like a global function or a static method. If they don’t, removal can be awkward or impossible without workarounds. Anonymous functions attached to hooks can’t be removed at all, because there’s no way to reference them again. That’s one reason to avoid anonymous functions for hooks in code others might need to customise.
Creating your own hooks
When you build plugins or themes, add your own hooks so other developers, or future you, can customise behaviour without editing your code:
Prefix hook names with your plugin or theme name to avoid clashes. Document what each hook does and what it passes. Thoughtful hooks are the mark of a professionally built plugin.
Debugging hooks
When a hook isn’t behaving:
- Check whether it fires at all. Add a temporary error_log call inside your function.
- Check priority. Another function might run after yours and override it.
- Check timing. Make sure your add_action or add_filter runs before the hook fires.
- Inspect attached functions. Query Monitor’s hooks panel shows which functions are attached to each hook on the current page, with their priorities.
You can also inspect the global $wp_filter variable, which holds every registered hook, though Query Monitor is far easier to read.
Common mistakes
- Forgetting to return a value in a filter.
- Using an action when a filter is needed, or the reverse.
- Not specifying accepted arguments when you need more than one.
- Attaching to a hook too late, or calling functions too early.
- Trying to remove a hook with the wrong priority or before it’s added.
- Running expensive code on hooks that fire many times per request, like the_content in loops or gettext.
Frequently asked questions
What’s the difference between an action and a filter?
Actions let you run code at a certain point, without returning anything. Filters let you modify a value and must return it. Technically, both use the same underlying system; the difference is how they’re intended to be used.
How do I find which hook to use?
Search the WordPress Developer Resources, read plugin documentation and inspect hooks firing on a page with Query Monitor. For WooCommerce, the official documentation lists many hooks, and reading template files reveals hooks used within them.
Why doesn’t my remove_action work?
Usually the priority doesn’t match, the removal runs before the hook was added or the function is a class method or anonymous function you can’t reference.
Can hooks slow down my site?
Hooks themselves are efficient. The code attached to them can be slow. Be careful with heavy work on frequently fired hooks.
Final thoughts
Hooks are WordPress’s way of saying “customise me without breaking me”. Actions let you do things at the right moment, filters let you change values before they’re used, priority controls order and accepted arguments give you the data you need. Learn the key hooks, always return values from filters, mind the timing and add your own hooks to code you write. Once hooks click, WordPress becomes a far more flexible platform to build on.




