A Guide to Overriding Parent Theme Functions in Your Child Theme

If you've had any experience working with parent and child themes in WordPress, you'll know that the template files in your child theme override those in your parent theme. So for example if your parent theme has a page.php file and you create a new one in your child theme, WordPress will use the one in the child theme when displaying pages.

You might think that functions would work in the same way: create a new function in your child theme's functions.php file with the same name as one in the parent theme, and it'll take precedence. Unfortunately it isn't as simple as this.

In this tutorial I'll show you three methods you can use to override functions from the parent theme in your child theme:

pluggable functions
function priority
removing functions from the hook they're attached to

How Functions in Parent and Child Themes Work

Before examining the methods for overriding functions in your child themes, it helps to understand how functions work in parent and child themes.

Firstly, you need to know that all of the functions in your parent theme will be run when you're using a child theme. You don't have to add anything to your child theme's functions file to make this happen. This is different from CSS, where you have to manually include the parent theme's stylesheet in the child theme's stylesheet.

The functions in your child theme will be loaded before the functions in the parent theme. This means that if your parent and child themes both have functions called my_function() which do a similar job, the one in the parent theme will load last, meaning it will override the one in the child theme.

However you can change the order in which functions are fired, and you can prevent functions from being fired altogether, as we'll see shortly.

Pluggable Functions

Pluggable functions are something you code into your parent theme, so they won't be any use to you if you're working with an existing parent theme that doesn't have them.

But if you're writing your own parent theme, maybe as a starting point for future projects, or if you're creating your own theme framework, it's good practice to make your functions pluggable so that you can easily override them in child themes. It's also a good idea to look through the functions that are written into the parent theme you're using, as many of them, including the WordPress default theme, will have pluggable functions.

To write a pluggable function, you simply enclose it in a conditional tag to check if a function with that name has already been run:

<?php
if ( ! function_exists ( 'my_function' ) ) {
    function my_function() {
        // Contents of your function here.
    }
}
?>

So if you enclose the functions in your parent theme in a conditional tag like this, WordPress will check if there is a function with the same name in your child theme that's already been run, and if that's the case it won't run the function from the parent theme.

Then when you come to write a function in your child theme which you want to override the one in the parent theme, you just give it the same name as the one in the parent theme:

<?php
function my_function() {
    // Contents for your function override here.
}
?>

WordPress will run the function in the child theme first, and when it comes to the one in the parent theme, it'll check if it already exists and because it does, it won't run it.

Function Priority

If you're not using your own parent theme, or you're using a third party one without pluggable functions, you'll need another method.

When you write functions you can assign them a priority, which tells WordPress when to run them. You do this when adding your function to an action or filter hook. WordPress will then run the functions attached to a given hook in ascending order of priority, so those with higher numbers will run last.

Let's imagine the function in the parent theme isn't pluggable, and looks like this:

<?php
function parent_function() {
    // Contents for your function here.
}
add_action( 'init', 'parent_function' );
?>

This function is attached to the init hook and hasn't been given a priority. By default WordPress assigns a priority of 10 to functions which haven't had a priority added, so to fire your function after it you use a number larger than 10. I tend to use 15 so I've got some breathing room in case I want to add another function between the two later on.

This means the function in your child theme would look like this:

<?php
function child_function() {
    // Contents for your function here.
}
add_action( 'init', 'child_function', 15 );
?>

Alternatively, the function in your parent theme may have had a priority assigned to it:

<?php
function parent_function() {
    // Contents for your function here.
}
add_action( 'init', 'parent_function', 20 );
?>

So you just need to make sure the priority you give the function in your child theme is higher:

<?php
function child_function() {
    // Contents for your function here.
}
add_action( 'init', 'child_function', 25 );
?>

Removing Functions From Hooks

Sometimes running another function after the first one isn't enough to override it—you need to make sure the function in the parent theme doesn't run at all. In this case, you can remove the parent theme function from the hook it's attached to, using the remove_action() or remove_filter() functions. The one you use will depend on whether the function is attached to an action hook or filter hook in the parent theme.

So let's return to our previous function in the parent theme:

<?php
function parent_function() {
    // Contents for your function here.
}
add_action( 'init', 'parent_function' );
?>

To remove this function from its action hook and therefore prevent it from firing, you create a function in your child theme to remove it using remove_action():

<?php
remove_action( 'init', 'parent_function' );
?>

However, this won't work on its own—you need to attach this function to a hook which will fire after the hook which the parent theme function is attached to. This is because you can't remove the action before it's been fired. You can find details of the order in which actions are fired in the Codex.

<?php
function child_remove_parent_function() {
    remove_action( 'init', 'parent_function' );
}
add_action( 'wp_loaded', 'child_remove_parent_function' );
?>

Once you've done this, you can simply write an alternative function to replace the parent theme function in your child theme's functions file, or you can do nothing if all you wanted to do was remove the functionality from the parent theme.

A Note on Priorities

Note that if you're trying to remove a function using remove_action() or remove_filter() and the function has had a priority assigned to it, you must include the priority when removing it, or it won't work.

So if the function in the parent theme looks like this:

<?php
function parent_function() {
    // Contents for your function here.
}
add_action( 'init', 'parent_function', 15 );
?>

... you'll need to include the same priority value when removing it:

<?php
function child_remove_parent_function() {
    remove_action( 'widgets_init', 'parent_function', 15 );
}
add_action( 'wp_loaded', 'child_remove_parent_function' );
?>

Summary

Overriding functions in a parent theme is more complicated than overriding template files or styling, but it can be done. Here I've shown you three methods for doing this:

If you're writing your own parent theme, or using one which has them, use pluggable functions so that a function in the child theme with the same name as one in the parent theme will replace it.
Assign higher priorities to functions in your child themes to ensure they're run after those in your parent theme.
Use remove_action() or remove_filter() to remove functions in the parent theme altogether.

Which method you use will depend on the way your parent theme is coded and whether you need to remove the parent theme function altogether or just run another function after it to override it.

HIGHLIGHTS OF THE DAY