What Are Filters in WordPress and How to Use WordPress add_filter 

A WordPress filter is a hook that manipulates internal data before it is displayed on the browser. To create a filter, add the add_filter function in your website’s functions.php file.

In WordPress development, users use this filter to modify a plugin, a theme, or specific website functionality. For example, you can change your website posts’ excerpt length or add a footer note to the articles.

In this WordPress tutorial, we will explain how to use the add_filter function to create a filter hook. We will also explore the function’s parameters and provide its common use case examples.

Download All in One WordPress Cheat Sheet


A WordPress filter is a hook that modifies data before it is returned to the database and displayed to the users. As a result, you can customize plugins, themes, or websites’ functionality without altering the WordPress core files.

For example, add a footnote to all website posts or change their excerpt length. There are four common filter hook functions – add_filter, remove_filter, has_filter, and doing_filter.

How WordPress Filters Work

In short, filters intercept data that WordPress passes. They modify it based on the given function and display it to users’ web browsers. To help you understand, look at this snippet:

// Specify the filter and the callback function
   add_filter( 'example_filter', 'example_callback' );
   // Define the callback function
   function example_callback( $example ) {
      // alter $example by concatenating on it
      $example . ‘ add a text at the end ’;
      return $example;
   }

Here’s the explanation of the example:

  1. Set a filter using the add_filter function that will modify the data. In our case, the filter name is example_filter.
  2. Define the callback function that will run when WordPress finds the filter, namely example_callback.
  3. Specify how the callback function will modify the data, which the $example argument represents. In the snippet, we will use the full stop to concatenate it with a sentence at the end.
  4. Display the modified data to the user’s web browser using the return method.

To apply a filter hook to your WordPress website, write the code in your currently-active theme’s functions.php file. If you use Hostinger’s WordPress hosting service, open File Manager and navigate to public_html/wp-content/themes/yourthemefolder.

The functions.php file location in hPanel's File Manager

Furthermore, we recommend adding the code to your child theme’s file to prevent it from disappearing after an update. Alternatively, create a separate file for the filter hooks in the theme root folder and write the following code in the functions.php file to call it:

include _once( get_template_directory(), ‘/yourfilename.php’:’

If you can’t access the theme root folder, install a plugin to add the custom code directly from your WordPress admin dashboard. A popular plugin for this task is Code Snippets.

Important! Modifying the functions.php file may lead to an error or an inaccessible website. To avoid this, create a backup before proceeding.

WordPress add_filter Parameters

The WordPress add_filter function has four parameters. Here’s each of them:

  • Hook name. The filter name you want to hook the callback functions into.
  • Callback function. The callback function to be run when the filter is applied.
  • Priority. An optional parameter specifying the execution order of functions associated with a filter. The default value is 10, and the lower the number, the earlier it executes.
  • Accepted arguments. The number of arguments passed to the hooked functions. This parameter is optional and has the default value of 1.

The function and parameters syntax is as follows:

add_filter( hook_name, callback_function, priority=1, 
   accepted_arguments=1);

Examples of add_filter in WordPress

The WordPress filter hooks let users change or add various new functions to their websites. For your reference, this section will explore some example code snippets.

Changing Post Excerpt Length

A simple example use case of a WordPress filter is changing the default posts’ excerpt length. Here’s the code snippet:

 add_filter( ‘excerpt_length’, ‘change_length’ );
   function change_length( $length )
   {
      // change the default excerpt length
      return 20;
   }

In the snippet, we created a function that changes the post excerpt length, which the $length argument represents. Then, we hooked the function to the excerpt_length filter.

When the data passes through the filter, the function will run and alter it accordingly. Then, the return method will limit the excerpt length to 20 and pass it to the user.

 Modified WordPress posts snippet length

Important! For some WordPress themes, you must also edit the content.php file to apply the excerpt filter. Read our tutorial on how to change the WordPress excerpt length to learn more about it.

Modifying Posts Content

A common use of the add_filter function is adding new content to your website posts. For example, here’s a code snippet example that places a disclaimer at the bottom of every website post:

 add_filter( ‘the_content’, ‘add_disclaimer’ );
   function add_disclaimer( $content )
   {
      // concatenate the content to modify it
      return $content . 
      “<br><center><strong>All writings and opinions are my own“;
   }

The example has the the_content filter, which hooks to the add_disclaimer callback function. When the filter runs, this function will modify $content by concatenating it with the All writings and opinions are my own disclaimer message.

The code will return the modified content to the browsers with the disclaimer at the bottom.

A disclaimer message underneath a WordPress post

Showing Image to a Specific Post Category

The WordPress filter hooks let you customize posts with a specific ID or category. In the following snippet, we added an icon to every post that belongs to the premium category:

add_filter( 'the_content', 'content_filter' );
   function content_filter( $content ) 
   {
      // condition where the function applies
      if ( in_category('premium') )
      $content = sprintf(
         '<img class="premium-icon"    
         src="%s/directory/filename.png"alt="Premium Content Icon"  
         title="" />%s', get_bloginfo( 'stylesheet_directory' ), 
         $content);
      return $content;
   }

In the example, we created the the_content filter and hooked it with the wpb_content_filter callback function. The function specifies the condition where the filter will apply.

In this case, if the post belongs to the premium category, the filter function will alter the content by adding an image to it.

An icon on a post from a specific category

Changing the Number of Displayed Products

A filter also lets you modify an eCommerce plugin to customize your online store. For example, here’s a custom code that changes the number of displayed products on the WooCommerce plugin:

add_filter('storefront_products_per_page','alter_sf_products_per_page' );
   function alter_sf_products_per_page() 
   {
      // change the default value
      return 3 ;
   }

In the snippet, we created the storefront_products_per_page custom filter and hooked it with the alter_sf_products_per_page function. When the data passes through it, the filter will call the function to change the default value from 12 to three and display it to the users’ browsers.

Products on an eCommerce WordPress website's storefront

Suggested Reading

Learn more about WordPress Function:
How to Use WordPress get_post_meta Function

Other Commonly Used WordPress Filters

In addition to add_filter, here are several other functions that developers may use with the filter hook.

remove_filter()

This function removes a function hooked to a specific filter. Web developers commonly use this to delete the default WordPress function without removing the code entirely. Here’s the syntax:

remove_filter( hook_name, callback_function, priority = 10 );

doing_filter()

This function checks if another function is currently being executed. It takes a hook name as the parameter and outputs either a true or false return value. The syntax is as follows:

if doing_filter( 'hook_name’ )
{ 
// execute a script if the filter is running 
};

has_filter()

The has_filter function verifies if a filter is successfully applied to a hook. It takes a filter name as the first parameter and the callback function as the optional second one.

To check a specific function, you must include the second parameter. Otherwise, it will return true to indicate that any function is hooked to the filter. The function’s syntax is as follows:

has_filter( ‘hook_name’, ‘callback_function’ );

Conclusion

A filter is a WordPress hook for modifying data before displaying it on the website. Web developers use it to customize a plugin or a theme to add extra functionality to their websites.

The filter hook will intercept data WordPress passes, alter it based on your needs, and display it to visitors’ browsers. To set a filter, write the add_filter function with the hook name and the callback function as the parameters in your theme’s functions.php file.

The filter hook’s example use cases include changing article excerpt length and adding a disclaimer to website posts. In addition to add_filter, its other functions include remove_filter, doing_filter, and has_filter.

Should you have any questions or comments, feel free to leave a comment below.

Author
The author

Aris Sentika

Aris is a Content Writer specializing in Linux and WordPress development. He has a passion for networking, front-end web development, and server administration. By combining his IT and writing experience, Aris creates content that helps people easily understand complex technical topics to start their online journey. Follow him on LinkedIn.