How to: Correctly Include JavaScript Files in WordPress Themes

23rd November 2012

There are quite a few ways to include JavaScript files into a theme, but only one method that is recommended by WordPress. The reason? To ensure maximum compatibility with updates and plugins, and avoid scripts being called multiple times. Following their guidelines, whether you’re handing over to a client, developing for yourself, or putting out a free theme under GPL, should save you a whole host of headaches in the future.

I’m going to cover how you correctly include JavaScript files in your WordPress Themes, but first here are a few things you should know.

  1. A number of common libraries, including JQuery, are already bundled with WordPress. This is something to be aware of before you start trying to call external files all over the place unnecessarily. WordPress lists these here.
  2. It is helpful to make sure you know where in your theme certain scripts need to be loaded. You don’t want to call a script meant for the home page post slider in admin – that’s how you end up slowing things down and creating conflicts.

To get started, you’re going to need to open your functions.php file, usually found in the root of your theme directory. You should also familiarise yourself with these two functions – wp_register_script and wp_enqueue_script. Registering a script makes it available for use. Enqueuing pulls the script to the theme.

NB: It’s possible to register scripts without enqueuing them and it’s possible to enqueue scripts without registering them (but it means more enqueue parameters). We’re going to register first and enqueue second in order to keep things neat and organised.

Bundled scripts

Bundled scripts are pretty simple because you don’t need to register anything new, just call them. For that, as with everything else in this tutorial, we’re going to use wp_enqueue_script.

Over-riding the bundled version

Of course, there might be times you want to over-ride the bundled version of a certain script, in this case JQuery. This is probably only advisable if you’re maintaining the site yourself, not if you’re releasing the theme. If you really need to do it, here’s how:

First, we’re going to de-register the bundled script. Then we’re going to register the version we want, this time from Google’s CDN. Then we’re going to enqueue it as normal.

Custom scripts

Loading a custom script is much like loading a bundled script, except that you need to register it before you can use it. When you register a script, you can specify whether it requires any other scripts in order to run. In this example, we’re going to load a custom script which is dependent on the JQuery library:

Conditional calls

If you want to load a script only on certain pages, you’ll need to use some conditional statements. In this example, we’re going to load the custom script from above on the front page only.

Jo was very professional, approachable and knowledgeable. She managed to fix all the issues with our charity WordPress site in super-quick time, as well as giving me a thorough and easy to understand tutorial, enabling me to amend the website myself in future. I will certainly use her services again in the future.

Maggie Davies (Footsteps Foundation)