Custom functionality

Welcome to this lesson dives into the theme’s functions file (functions.php) and how you can use it to add your own.

The functions.php file

What is the purpose of a WordPress theme’s functions.php file?

Adding features or functionality to your theme can be accomplished by adding the optional functions.php file introduced in the Beginner WordPress developer learning pathway. Do check out the lesson on Theme structure.

We can choose to add the functions.php file in order to extend WordPress without changing the files by using the WordPress hook system. To learn more about WordPress hooks, you can refer to the module found within the Beginner developer learning pathway.

Like plugins, you should always run your code on a hook so that it performs its functionality at the appropriate point in the load process. For example, you could add various theme support features after your theme is initialized by WordPress by using the after setup theme action hook and the add theme support function.

Here’s a look at the functions.php file included in the default Twenty Twenty-Four theme. The register block pattern category function registers the page’s pattern category for us here.

Note that WordPress Core already provides us with many pattern categories. It just so happens that this particular pattern category is not provided, so the theme is doing it for us. This will run the Twenty Twenty-Four pattern categories function when the init hook is executed.

Using a plugin

How do you know when to use a plugin instead of the functions.php file?

Since you can add plugin-like features to your theme, it’s important to use this power wisely. If you plan to distribute your theme, you’ll want to consider placing your code within a plugin rather than relying on the functions.php file. And this way, a website owner’s site won’t break if they decide to replace their theme.

If you plan to submit your theme to the WordPress.org theme directory, you’ll want to be sure to follow the guidelines there.

Common uses

Let’s take a look at some common uses of the functions.php file for extending functionality of WordPress.

For classic themes, you could use the functions.php file to add block theme styles. If you take a look at the Twenty Twenty-One theme, you’ll see an example of this where they add theme support for block styles to this classic theme.

// Add support for Block Styles.
add_theme_support( 'wp-block-styles' );

You can also load scripts and styles with the functions.php file, which we’ll be covering in the next lesson on including assets. To see an example of this, though, you can take a look at the Twenty Twenty-Two theme.

And finally, you can choose to include other PHP files by using the functions.php file. You can refer to the Twenty Twenty-Two theme again for an example of this, and you’ll find that it uses the block-patterns.php file located in the inc folder.

// Add block patterns
require get_template_directory() . '/inc/block-patterns.php';

This is done by adding require, get template directory, and concatenating the file path.

Next steps

You can learn more about adding custom functionality by referring to the theme handbook available to you on WordPress.org.