How To Load Custom JavaScript In WordPress

Often times, adding custom JavaScript for analytics tracking is the first type of custom code a WordPress user has to implement. Normally the documentation that you are given with these codes are written as if your site is just a bunch of HTML files. But that’s not how WordPress works. The HTML of your site is dynamically generated.

In two recent posts on this site, I discussed JavaScript and the other languages used in WordPress and how to implement custom code on your WordPress site. In this post, I will go into more detail on the best ways to work with JavaScript snippets you need to add to your site.

Ways To Add Custom JavaScript To Your Site

Here is a quick list of options for adding JavaScript to your WordPress site. They all will work, but some are better than others. I’ll go over each in detail in this article:

• Load a separate JavaScript file using WordPress’ script loader
• Use the wp_footer or wp_head hooks to add the script inline
• Use a plugin to add header or footer scripts
• Modify your theme to include the script (bad idea)
• Use the WordPress post editor (really bad idea not worth discussing)

The first two options involve using WordPress hooks. I wrote a basic introduction to WordPress hooks previously for our blog. I also covered how to use WordPress hooks in my WordCamp Tampa talk, here are the slides which go over actions and filters:

Obviously these options involve a little bit of custom coding. Depending on what you need that might be worth it. I’ll start with the no code solutions and go from there.

Adding Header And Footer Scripts With A Plugin

Most of the time when you need to add custom JavaScript it is because you need to add something like Google Analytics tracking code to your WordPress site. Or you might need Facebook or Twitter pixel tracking code.

These are very simple cut and paste operations. For something simple like this a plugin is a good choice.

Facebook, Google, Twitter or whomever gives you the code and tells you to paste it into your site’s header or footer. For a traditional static HTML site, you would literally paste that code into the HTML header or footer on each page. With WordPress you need to have that code injected into each page’s header and footer programmatically.

There are a lot of plugins out there for header and footer scripts. I recommend the Insert Headers And Footer plugin. It’s simple, easy to use and works.

Don’t Edit Your Theme’s Header or Footer Files

Every WordPress theme has a header.php and footer.php template file. Those files should generate the header and footer of your theme. You technically could just paste tracking code or other JavaScript there. That would work, but please don’t.

A modification to a theme file will be lost when you update your theme. That’s bad. In addition, if you ever change your theme, you will lose that tracking script, which is also bad. Separating everything that doesn’t have to do with how your site looks from the theme means that when you change how your theme, only the visuals change and you don’t lose important functionality.

Adding JavaScript Inline With WordPress Hooks

If you’re OK with writing a little custom code, I would recommend creating a WordPress plugin for loading small bits of code into your site’s header or footer via an action. For small bits of code it doesn’t make sense to use a separate JavaScript file, that would require and therefore extra HTTP request when loading the page.

This is the equivalent of modifying header.php or footer.php with none of the downsides I discussed in the last section. WordPress actions are type of hooks that allow you to do something when that action is encountered by WordPress. When your theme runs header.php, it should cause the action wp_head to run — probably via the wp_head() function.

When the wp_head function is “fired” we can “hook into it” and tell WordPress to execute some code. For example to print some inline JavaScript. Here is a complete WordPress plugin that you can upload to your plugin directory and use:

All that does is open an alert that says “Hi Roy”, but you could put your own script there to do whatever you wanted.

That’s not hard is it?

A footer script plugin would be almost identical, except you would use the “wp_footer” action.

This is basically what any add header and footer scripts plugin does, just more efficient. Those plugins have to have a user interface, database queries and more. A custom plugin for header and footer scripts is a few minutes more work, but it will save load time and be less hassle over time.

How To Include A JavaScript File In WordPress The Right Way

WordPress has  a system for loading JavaScript and CSS files. For JavaScript files, you can use the function wp_enqueue_scripts, inside of a callback function hooked to the wp_enqueue_script action to load a file. For large amounts of JavaScript this is a good idea.

You could just write a normal HTML script include tag into header.php or footer.php but this is bad practice. The wp_enqueue_script system manages the order scripts are loaded, scripts they are dependent on and dynamically generates the URL.

Here is an example of loading a script called “custom-scripts.js” that is in your child theme’s main directory using wp_enqueue_scripts:

This bit of code would go in the child theme’s functions.php because the JavaScript file is in the child theme itself. I’ll show another example for a custom plugin as well in a bit.

Note that I used get_stylesheet_directory_uri() to dynamically generate the URL to my child theme instead of assuming the URL path. This is an important best practice. If your site changes its URL, you want your custom JavaScript to keep loading. If you move from insecure HTTP to HTTPS, which you should, you will need your scripts to load over HTTPS or you will get mixed content warnings that are likely to break key functionality.

Before accepting “works for now” consider the headaches you’re inviting yourself for later by ignoring best practices.

Speaking of which, notice the third argument is an array with one value “jquery.” This tells WordPress that before this script is loaded, to load jQuery. WordPress includes a copy of jQuery. Loading your own version of jQuery can be a risky move and must be done right. Loading an additional copy of jQuery is a bad idea.

If you wanted to make a plugin that loaded custom JavaScript, it would be very similar, but you need use the function plugin_dir_url() to generate the URL. Here is an example where the JavaScript file is in the same directory as the plugin:

Dog and cat images are from WikiCommons. CC) licensed and super adorable.