A Guide to Actions and Filters in WordPress

wordpress hooks: actions and filters

WordPress comes with this built-in API that allows us to hook custom functionality into the rest of WordPress. We can provide that extra functionality through plugins or themes. These are called hooks and they are either actions or filtersActions allow us to run custom functions at a certain points of a request, while filters allow us to process and change data at these certain points.

The gist of the difference between actions and filters is:
Actions modify functionality; filters modify data.

WordPress makes heavy use of actions and filters for its own core functionality. Thus, we can use actions and filters to modify WordPress default functionality  or add our own on top of it. WordPress ships with an extensive lists of actions and filters that we, as developers, need to accustom ourselves with.


To employ actions and filters we need to use these two functions: add_action() and add_filter(). Both of them take four same arguments. The first two arguments are required and the two others are not and we won’t find ourselves using them a lot.

We hook custom functionality into WordPress like this:

add_action( 'hook_name', 'our_custom_action', [priority], [accepted_args] );

We use custom filters to transform data passed through WordPress like this:

add_filter( 'hook_name', 'our_custom_filter', [priority], [accepted_args] );


Actions are triggered at specific times during the request. In front-end it can be the time when the header or footer is loaded, giving us the ability to put our scripts at those sections. In back-end it can be the time when a post is published so that we can email our subscribers to notify them that a new post is published on our blog.

In the example action below the function changes default WordPress functionality by modifying the default image link type. By default it is set to Media File and we want it to default to None so we can save a couple of clicks when we insert images into a post. We hook this functionality in the admin_init action, which runs before any other hook when a user accesses the admin area.

function ns_image_link_type()
    $image_set = get_option('image_default_link_type');

    if ($image_set !== 'none') {
        update_option('image_default_link_type', 'none');
add_action('admin_init', 'ns_image_link_type');

In such a fashion we run every action to modify WordPress default functionality or to add extra functionality to it.


Filters are functions which modify data that WordPress passes through them before showing that data to the user or inserting it into the database. Filters take in data and modify it and then return it so other filters can continue to process it.

In the example filter below, it default data by modifying the classes added to body by default through the body_class() function. Through this filter we append a class name to the list of default classes. Our theme relays on this class for showing the right color scheme based on what the user has saved in theme customizer, i.e. either light or dark.

function ns_body_class($classes)
    // light or dark color scheme
    $classes[] = get_theme_mod('color-scheme', 'light');
    return $classes;
add_filter('body_class', 'ns_body_class');

This is the way to filter data in WordPress. It’s very similar in structure to actions.

Custom Actions and Filters

Up to now we have talked about how we can use actions and filters that ship with WordPress. However, WordPress allows us to create our own actions and filters through plugins and themes. Custom actions and filters are helpful to make our themes and plugins extendible through child themes or other plugins without needing the edit the source files.

Custom actions and filters are created and called in the same way that core WordPress hooks are, through do_action() and apply_filters().

In the sample custom action hook below we want to add extra elements after the post content, we can add an action hook in our appropriate theme file like this:

<?php do_action('after_content'); ?>

To hook into that action, so that we can, for example, show author bios or other elements like ads, we will have to run something like this:

function ns_author_byline() 
    get_template_part('parts/author', 'byline');
add_action('after_content', 'ns_author_byline');

On the other hand, for our custom filter hook, let’s say we want to add more color schemes to our default ones, dark and light that we talked above. In this case we want the default list of colors schemes to be extendible through a child theme. We will have have to create a custom filter hook like this:

function ns_color_schemes()
    $color_schemes = array('light' => 'Light', 'dark' => 'Dark');

    return apply_filters( 'ns_schemes_filter', $color_schemes );

To hook into this filter and expend the list with more color schemes, we run something like this:

function ns_add_color_schemes( $color_schemes ) 
    $color_schemes['yellow'] = 'Yellow'; 
    $color_schemes['blueish'] = 'Blueish'; 

    return $color_schemes; 
add_filter( 'ns_schemes_filter', 'ns_add_color_schemes' );

The end result will be that on our customizer now will show four color schemes rather then the original two.

Custom hooks into our themes or plugins make our code extensible so that we, or others, can modify and extend.

Keep learning

Actions and filters are a powerful tool at the hand of the developer and a great way to modify default WordPress functionality and to extend it. I  hope this article has taught you something new and valuable for your everyday work. To not miss new articles, consider subscribing to my newsletter.

Baki Goxhaj
I’m a web consultant specializing in WordPress. I love elegant solutions, quality code and a good laughter.
You may also like
New WordPress Freelance Project: JDMNagoyaAutoParts
How to Install XAMPP on Ubuntu
1 Comment
  • Matthias Klenk Feb 26,2016 at 11:43 am

    Actions and filters are clearly an advantage in WordPress. But having to work on a project with many plugins from different developers can drive you nuts and you can lose the overview easily…

Leave Your Comment

Your Comment*

Your Name*
Your Webpage