How to Properly Add jQuery Scripts to WordPress

Get a free WP Checkup Today!
Get a completely free health check of your WordPress site, no email or signup required.

Despite the fact WordPress has been around for a while, and the method of adding scripts to themes and plugins has been the same for years, there is still some confusion around how exactly you’re supposed to add scripts. So let’s clear it up.

Since jQuery is still the most commonly used Javascript framework, let’s take a look at how you can add a simple script to your theme or plugin.

jQuery’s Compatibility Mode

Before we start attaching scripts to WordPress, let’s look at jQuery’s compatibility mode. WordPress comes pre-packaged with a copy of jQuery, which you should use with your code. When WordPress’ jQuery is loaded, it uses compatibility mode, which is a mechanism for avoiding conflicts with other language libraries.

What this boils down to is that you can’t use the dollar sign directly as you would in other projects. When writing jQuery for WordPress you need to use jQuery instead. Take a look at the code below to see what I mean:

The good news is that with a few modifications you can go back to the lovely little dollar sign once again! Writing jQuery out so many times makes the code longer to write and more difficult to read.

Just to recap if you’re learning jQuery, the $ sign is just an alias to jQuery(), then an alias to a function. The basic syntax is: $(selector).action():

  • A dollar sign to define jQuery
  • A (selector) to “query (or find)” HTML elements
  • A jQuery action() to be performed on the element(s)

If you’re loading your script in the footer, you can wrap your code in an anonymous function, which will map jQuery to $. Here’s how:

If you want to add your script in the header – which you should avoid if possible – you can wrap everything in a document-ready function, passing $ along the way.

Linking Your jQuery Scripts

Now that you can write valid jQuery code for WordPress, let’s link our work to our website. In WordPress the process is called enqueueing. For a regular HTML website, we would use the <link> element to add scripts.

WordPress ends up doing the same thing, but we’ll use special WordPress functions to achieve it. This way, WordPress handles all our dependencies for us – thanks, WordPress!

If you’re working on a theme, you can use the wp_enqueue_script() function within your functions.php file. Here’s how.

The function takes five  arguments. The first is a handle you can use to refer to the script, the second is the location of the script file, the third parameter is an array of dependencies.

I’ve added jQuery as a dependency since the script uses it. If you create a script that depends on “my-great-script,” you should add it to the dependency list so WordPress knows which files to load first.

The fourth parameter is a version number and the fifth lets WordPress know where to put the script. By default, scripts will be loaded in the header, which is bad practice and will slow down the page loading of your site (browsers halt all loading whenever a <javascript> block is encountered). You should load all of your scripts in the footer when possible by making sure the fifth parameter is true.

Adding Scripts to the WordPress Admin

You can also add scripts to the admin. The functions used are exactly the same, you just need to use a different hook. Take a look at the example below:

Instead of hooking into wp_enqueue_scripts we need to use admin_enqueue_scripts. That’s it!

Using Conditional Tags

Use conditional tags to only load your scripts when necessary. This is more often used in the admin where you would want to use a script only on a specific page, not the whole admin. This saves bandwidth and processing time, which means faster loading times for your website.

Take a look at the admin_enqueue_scripts documentation in the WordPress Codex for more information.

Wrapping Up

Adding simple jQuery scripts to WordPress is not difficult at all once you know how. There is a little bit of an overhead compared to doing it in vanilla HTML, but there is also the added benefit of dependency management and clarity.

Do you use jQuery on your site? What other jQuery tips and tricks would you like to see on our blog? Let us know in the comments below.

Get a free WP Checkup Today!
Get a completely free health check of your WordPress site, no email or signup required.