The Difference Between WordPress Actions and Filters (for beginners)

If you want to customize something on your WordPress site using code, you use an action or a filter.

With an action or a filter, you can add something to a page, load Javascript or CSS, add information to a post before it is saved, and a thousand other things.

So what’s the difference between actions and filters? Let’s drop all the jargon and oversimplify this to make it easy.

The Difference

Actions do something at a specific point, filters modify a value and return it.

For example, with an action you can add information to a post before it is saved. With a filter, you can change the format of the date on every blog post.

With an action, you can put an ad on every page on your site. With a filter, you can make your site blog and category pages display 100 posts at a time.

Notice that the filters are taking something that is already there and modifying it. Actions are doing something extra at a specific time.

To understand this better, let’s look at actions and filters in more depth.

What are WordPress Actions?

Think of a page load on your WordPress site as a sequence of things that happen. Here’s an oversimplified example:

1. Load the plugins and theme
2. Initialize all the WordPress core code
3. Show our posts on the page

These 3 things are actions. What if we want to do something custom on our site, like show an ad? We hook into the third action and display our ad before the posts are displayed.

This type of action hook says “Hey WordPress, before you load the content, put this ad on the page.” You do this with the add_action() hook.

We can load our ad above everything using the wp_head action hook like this:

function my_header_hook() {
    echo '<div class="my-ad">Display ad here</div>';
}
add_action( 'wp_head', 'my_header_hook' );

There are other types of actions as well, such as an action that happens before a post is saved. The code below will send an email every time a new post is created using the save_post hook:

function my_new_post_send_email( $post_id ) {
 
    // If this is just a revision, don't send the email.
    if ( wp_is_post_revision( $post_id ) ) {
        return;
    }
 
    $post_title = get_the_title( $post_id );
    $post_url = get_permalink( $post_id );
    $subject = 'A new post has been created';
    $admin_email = get_option('admin_email');
 
    $message = "A post has been updated on your website:\n\n";
    $message .= $post_title . ": " . $post_url;
 
    // Send email to admin
    wp_mail( $admin_email, $subject, $message );
}
add_action( 'save_post', 'my_new_post_send_email' );

There are tons of WordPress core actions, and plugins and themes usually have their own actions too. This allows you to do pretty much anything you want at any time.

Actions have things called parameters, like $post_id which you can see in the save_post hook above. A parameter gives you information about the hook you can use. For example you can see above that we are checking if the post is a revision using the $post_id, if it is we are not sending the email. Actions can have several parameters that give helpful context like this.

What is a WordPress Filter?

While actions do something new at a specific time, a filter modifies an existing value and returns it.

For example, with a filter we can grab every post date and add the text “Updated on:” in front of it so it reads “Updated on: September 29th, 2020.” That would be done like this:

add_filter('get_the_date', 'my_date_filter', 10, 3 );

function my_date_filter( $date, $format, $post ) {
	return 'Updated on: ' . $date;
}

Let’s compare this to an action. With an action, we could also add the text “Updated on” before the date, but we could not modify the actual date itself. For example if we wanted to change the date format, we cannot do that with an action, only a filter.

Another interesting use for a filter is to change how posts are displayed on your site. Using the pre_get_posts filter, you can change the main post query to only show certain categories:

function my_filtered_query($query) {
    if ($query->is_main_query()) {
        $query->set("category_name", array("business", "sports"));
    }
}
add_filter("pre_get_posts", "my_filtered_query");

Filters have parameters that give context, just like actions. Custom filters can also be added by plugins and themes. You can see all available WordPress core filters here.

Summing Up the Difference Between Actions and Filters

Filters and actions are both very useful tools, and allow you to customize almost anything about WordPress. When deciding which one you need to use, try asking yourself if you want to do something new, or change an existing value.

If you want to do something new at a specific time, use an action.

If you want to change an existing value, use a filter.