One of the biggest strengths of WordPress lies in its extensibility — the ability for developers to add, change, or enhance functionality without touching core files. This flexibility is made possible through the WordPress Hook System, which lets you “hook” your own custom code into predefined points during WordPress’s execution. Two of the most important hook functions in this system are add_action() and add_filter().
At first glance, these functions might seem similar. Both allow you to connect your own functions to WordPress’s workflow. Both use hook names, callback functions, and priorities to determine when and how they run. However, they serve different purposes, and understanding the distinction is essential for writing clean, maintainable code.
add_action() is used when you want to perform a task at a certain point — for example, enqueueing scripts, sending an email when a post is published, or adding extra HTML to a page. Actions are all about doing something when WordPress triggers a particular event. They don’t return data to WordPress; they simply execute and finish.
add_filter(), on the other hand, is used when you need to modify data before it’s used or displayed. Filters take in a value, process it (optionally modifying it), and then return that value. They’re perfect for changing post content, customizing excerpts, altering widget titles, or tweaking query results. Without the return value, filters won’t work as intended.
Knowing when to use an action versus a filter can make the difference between a plugin that works reliably and one that causes strange errors. In this article, we’ll break down how both functions work, explore their similarities and differences, and look at practical, real-world examples so you can confidently apply them in your own WordPress projects.
WordPress is built on a powerful hook system that allows developers to modify and extend core functionality without altering core files. Two fundamental hooks in WordPress are actions and filters, implemented via the functions add_action() and add_filter() respectively.
Understanding the difference between these two is crucial for anyone developing themes, plugins, or customizing WordPress behavior effectively.
What Are Hooks in WordPress?
Before diving into add_action() and add_filter(), it’s important to understand what hooks are.
Hooks are points in the WordPress execution where you can attach your custom functions. They come in two types:
Actions: Trigger custom code at specific points in execution.
Filters: Modify data before it is used or output.
Both are implemented using the Hook API — WordPress’s event-driven system that allows code to be “hooked” in to run or modify behavior.
What is add_action()?
add_action() registers a custom function to an action hook. When WordPress reaches this hook during execution, it calls all functions registered with it.
Purpose:
To perform an action or task at a specific point.
Actions don’t expect to return data. Instead, they are used for side effects like output, database changes, logging, or triggering other processes.
How it Works:
WordPress calls the function(s) attached to an action hook.
These functions execute and do not modify or return any data back to WordPress.
Common Use Cases:
Enqueuing CSS and JavaScript files.
Sending emails after a post is published.
Creating custom post types on plugin activation.
Adding content to admin screens or front-end areas.
Scheduling tasks or cron jobs.
Example:
add_action('wp_footer', 'display_custom_footer_message');
function display_custom_footer_message() {
echo '<p>Thank you for visiting our website!</p>';
}
This adds a message to the footer of your WordPress site. The function runs when WordPress processes the wp_footer action hook.
What is add_filter()?
add_filter() registers a custom function to a filter hook. When WordPress processes data through that filter, it passes the data to your function. Your function can then modify the data and must return it.
Purpose:
To modify or filter data before WordPress uses or outputs it.
Filters expect the hooked functions to return a value — often the modified input.
How it Works:
WordPress passes data to the filter functions.
Your functions modify (or leave unchanged) the data and return it.
The final returned value is used by WordPress or displayed.
Common Use Cases:
Altering the content of posts or pages before display.
Changing excerpt length or formatting.
Modifying widget titles or output.
Adjusting email subjects or sender information.
Filtering query arguments or results.
Example:
add_filter('the_content', 'append_custom_text_to_content');
function append_custom_text_to_content($content) {
return $content . '<p>— Thank you for reading!</p>';
}
This appends a thank-you message to the end of every post’s content before it is displayed.
| Aspect | add_action() | add_filter() |
|---|---|---|
| Purpose | To execute code at specific points | To modify and return data before use |
| Returns value? | No (void) | Yes, must return the (modified) value |
| Typical Usage | Triggering side effects like output or logic | Altering variables, strings, arrays, objects |
| Parameters | Hook name, callback function, priority, args | Hook name, callback function, priority, args |
| Callback inputs | Usually no input or contextual parameters | Receives data to modify |
| Effect on WordPress | Perform actions but do not change data | Change data passed through the filter |
| Examples | wp_enqueue_scripts, save_post, admin_init | the_content, widget_title, excerpt_length |
How Do Priority and Arguments Work?
Both add_action() and add_filter() accept optional parameters for:
Priority: Determines order in which multiple functions attached to the same hook run. Lower number = earlier execution. Default is
10.Accepted Arguments: Number of arguments your callback function accepts. Default is
1.
Example:
add_action('init', 'my_function', 15, 2); // Priority 15, accepts 2 args
When to Use Each?
Use actions when you want to perform a task that doesn’t alter data, such as sending emails, logging events, or adding HTML output.
Use filters when you want to modify content or data before it is saved, displayed, or used internally.
Common Mistakes to Avoid
Not returning data in filter callbacks: If your filter function does not return the data, it may break site functionality or cause empty outputs.
Performing output in filter callbacks: Filters should return data, not echo or print HTML directly.
Using actions when you want to modify data: If you want to change content, use filters instead of actions.
Real-World Examples
1. Using add_action() to enqueue a stylesheet
add_action('wp_enqueue_scripts', 'enqueue_custom_styles');
function enqueue_custom_styles() {
wp_enqueue_style('my-style', get_template_directory_uri() . '/css/custom.css');
}
2. Using add_filter() to change the login logo URL
add_filter('login_headerurl', function() {
return home_url();
});
This changes the URL linked to the WordPress login logo to your homepage.
Both add_action() and add_filter() are essential hooks in WordPress plugin and theme development. They empower developers to extend and customize WordPress behavior safely and efficiently.
Actions execute code at specific points to perform tasks or side effects.
Filters allow modification of data passed through WordPress before use or display.
Mastering these two hooks will enable you to build flexible, maintainable WordPress extensions and improve your development skills dramatically.