At first glance, adding Javascript files to your WordPress theme seems like an relatively straightforward task.  Just open your theme’s header file and paste in a script tag, right?

Actually, it’s not quite that simple.  Adding a script tag directly into your theme’s header file does work fine in many cases, but has the potential to cause significant problems in your WordPress installation.  Read on to see the proper way to add Javascript files to your WordPress site.

Why Shouldn’t I Directly Add Javascript to my Site?

Consider the fact that most WordPress installations are running more than just a theme.  A WordPress installation is using a theme, yes, but in almost every case, it is also using plugins to extend the functionality of WordPress.

Plugins are great, but they all require their own files and code to extend WordPress, and in many of these cases, that code includes javascript. Plugins could end up rei-ncluding javascript that we’ve already included, or could include javascript that somehow conflicts with ours, so we need a way to manage javascript files that is effective across both themes and plugins.

Fortunately, WordPress provides an API to include Javascript in a centralized way that both plugins and themes can tie into.

The Proper Way To Add Javascript: wp_enqueue_script

Worpress provides the wp_enqueue_script method as the official way to add javascript files to your site.  Let’s look at the method signature:

wp_enqueue_script('jquery');

The wp_enqueue_script method takes several parameters:

  1. $handle – a unique name for your javascript file
  2. $src – a link to your javascript file
  3. $deps – the handles of any other javascript files your script depends on
  4. $ver – the version of your js file (useful when including javascript framwords)
  5. $in_footer – whether or not to include this file in the footer of your site instead of the header

The easiest way to explain this method is with an example, so let’s say we wanted to add jQuery to our WordPress theme.  In this case, we only need to fill out one parameter since WordPress already includes the jQuery library in every installation

wp_enqueue_script('jquery');

Now let’s say we wanted to add our own application javascript file to WordPress (let’s say it requires jQuery).  We could call the wp_enqueue_script again.

wp_enqueue_script('my_javascript_file', '/path/to/my_javascript_file.js', array('jquery'));

As you can see, we pass in a handle for our file, the path to the actual js file, and then array with the other javascript files ours depends on.  Passing in dependencies tells WordPress to load the script files in the correct order.

Where Do I Call wp_enqueue_script?

Now you know how to add a javascript file to your theme, but where do you put these calls?  The answer, for themes, is in your functions.php file.  However, you can’t just call wp_enqueue_script whenver, you want.  You have to link it to WordPress initilization action.  Again, an example is the easiest way to see how this works.

<?php
function load_scripts() {
   wp_enqueue_script('jquery');
   wp_enqueue_script('my_javascript_file', '/path/to/my_javascript_file.js', array('jquery'));
}    

add_action('init', 'load_scripts');
?>

We place the wp_enqueue_script calls in a function, that we’re calling load_scripts.  The name of this function isn’t important, but what is important is that we tie that function to the WordPress init action using the add_action call.  This add_action call tells WordPress to call our function when it initializes.  When load_scripts gets called it calls wp_enqueue_script to actually output the scripts to our page.

The cool thing about adding scripts this way is that WordPress is smart enough to make sure everything gets loaded up correctly.  Scripts that are enqueued multiple times will only get output once, and with the use of dependencies, all the scripts will be output in the correct order.

So now you’ve seen the correct way to add scripts to your WordPress theme or plugin.  Use it to make sure your scripts are deployed  in the most reliable way possible.  You can see a complete reference for wp_enqueue_script at the WordPress Codex