What Is a Filter in WordPress?

Filters are one of the two kinds of hooks in WordPress; the other kind is actions. A hook is a pre-defined spot in WordPress code where you can attach your own function, letting one piece of code interact with or modify another.

Filters let you modify data during the execution of WordPress core, themes, and plugins. Common filter hooks include the_title (the post title), the_content (the post body), and body_class (the CSS classes on the site’s body tag).

How filters work

You write a callback function, the code you want to run. WordPress passes it the current value, your function changes that value, and it must return the result, because whatever comes back is what WordPress uses. A callback that forgets its return statement hands back nothing, so the value comes out empty.

Register the callback with add_filter(), passing the hook name and your callback’s name; WordPress then calls it whenever that filter runs. add_filter() also takes two optional parameters: $priority, which sets the order your callback runs relative to others on the same hook (the default is 10, and lower numbers run first), and $accepted_args, the number of arguments passed to your callback (the default is 1). The WordPress Plugin Handbook documents both.

Example: adding a CSS class with body_class

The Plugin Handbook’s example adds a CSS class to the body tag of every public page. The callback wporg_css_body_class( $classes ) appends the class wporg-is-awesome to the $classes array when the visitor isn’t in the admin area, then returns the array. One line registers it: add_filter( 'body_class', 'wporg_css_body_class' ). From then on, WordPress runs the callback each time it builds the body tag’s class list, and the new class shows up in the page’s HTML.

Filters vs. actions

Both hook types run your code, but they do different jobs:

• Filters take a value, such as a post title, change it, and return it for WordPress to use. A filter should work in isolation, with no side effects like printing output or changing global variables.
• Actions run code when something happens at a specific point in execution, such as a post being saved, and can print output or write to the database. Action callbacks return nothing.

The decision rule: use a filter when you want to change data before WordPress uses it, and an action when you want to do something at a specific moment. Our hook entry carries the full comparison, and the custom hook entry covers creating hooks of your own.