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.


  • Robin

    30th June 2013 at 11:59 am

    Thanks for sharing the idea.

  • nev

    28th August 2013 at 10:55 am

    Thanks for this. It finally got me motivated to register and enqueue my scripts properly 😉

Leave a Reply

What our customers say:

Jo has been looking after my website for a couple of years now. She has just completed another refresh of the site for me, tidying up a few pages and installed a fantastic new booking system that has made a huge improvement to the functionality of the site. I’m really pleased with the result, and the website looks great. I can highly recommend Jo for all your website needs.

Andrew Tee (Get More Adventure)