Learn How to Add Custom JavaScript to WordPress the Right Way

Learn How to Add Custom JavaScript to WordPress the Right Way

You’ve taken time to learn how to use JavaScript in WordPress. You’ve also picked up a number of useful JavaScript libraries and resources along the way to streamline coding with it. But now what do you do with the skills you’ve acquired?

There are a number of reasons why you might want to add custom JavaScript to your WordPress site and there are also a number of ways in which you can implement it. But you have to be very careful about how you do this. The wrong implementation of JavaScript can do more harm than good.

In today’s quick guide to JavaScript tutorial, I’m going to talk about why you might want to add custom JavaScript to your site and how to do so the safe and proper way (including using WordPress plugins).

Why You May Want to Add Custom JavaScript to WordPress

When coding a WordPress site, there are three elements you need:

  1. HTML
  2. CSS
  3. JavaScript

HTML and CSS are great. They lay down a solid foundation for your WordPress site. However, they can’t help much if you want to alter the “behavior” of your site. For example, you’d likely need to use JavaScript to do the following:

  • Change, hide, or display HTML elements.
  • Add values to CSS variables and run complex operations on them like merge variables or provide a response after an action is taken (like a click).
  • Change the layout and design of your WordPress theme (if you’re prohibited from controlling certain elements).
  • Alter or enhance the functionality of a WordPress plugin.
  • Enhance your site with dynamic content like sliders, animation, video players, drop-down or hover effects, calculators, and other interactive elements.
  • Hook an external source or element into your site, like Google Analytics or a third-party API.

This is where JavaScript can help.

That said, JavaScript isn’t as simple to implement as HTML and CSS. Not only do you have to be careful about how you write the code, but you also have to be careful about how and where you add it to WordPress.

How to Add Custom JavaScript to WordPress

Once you’ve mastered HTML and CSS, and you really want to let loose on your WordPress site, it’s time to add custom JavaScript to it. But how do you do this and where do you put it? And, more importantly, does it even matter?

As a basic rule, JavaScript belongs in one of two locations:

  • In the head of your theme for site-wide applications of the script.
  • Within the body of a web page for page-specific applications.

And you don’t always have to place the full tag in those locations. If you want to keep your web pages running faster and your code easier to read, you can create separate JavaScript files (.js) and call on them using a reference like this:

http://filename.js

Sounds simple enough, right? Well, it sort of is, but you have to remember that JavaScript is a programming language. It’s not something you can easily inject into your web pages as you would HTML or CSS. So, here are some rules to follow as you go about adding custom JavaScript to your WordPress site:

Rule #1: Don’t Use the WordPress Editor


Unless you’re adding a very small script to a single page or calling on a file from it, the text editor for your WordPress pages and posts is not the place to write out your JavaScript. It will slow down the loading of your web page and can create a mess of the code.

Rule #2: Don’t Modify Your Files Directly


This rule pertains to your theme and plugin files. While JavaScript will help you add or change functionality to your WordPress integrations, it’s a bad practice to add custom JavaScript to those header files.

For starters, there’s the matter of your scripts clogging up the well-written code from the developer. One of the ways you keep your site running well is by relying on clean coding practices. And errant JavaScript can disrupt that.

Secondly, you’ll lose your custom JavaScript directives as soon as you update your theme or plugin files. While JavaScript does belong in the header of your theme and there is a header.php file that can be edited, don’t do that here.

Finally, if you’re thinking about circumventing this issue by creating a child theme and applying the custom JavaScript there, don’t. When you update the header.php or footer.php files with JavaScript, you may unintentionally create a conflict with plugins running on your site. This can either slow things down a lot or take your server offline completely as your site has no idea how to handle these simultaneous requests.

Note: This rule actually only pertains to WordPress developers using third-party themes or plugins. If you’re writing your own themes and plugins, you can add JavaScript directly to the header file; however, you’ll want to use an enqueuing system as detailed here.

Rule #3: Create Separate Files for JavaScript

If I’m telling you not to add JavaScript coding directly to your files or pages in WordPress, then how the heck are you supposed to get it in there? There are two ways to do this. One is to create a separate JavaScript file and the other, which I’ll detail in rule #4, is to use a WordPress plugin to add the custom JavaScript.

As I’ve mentioned already, adding custom JavaScript directly to WordPress can make a real mess of things and potentially cause serious problems like the white screen of death. But if you only want to apply the script to one page, then you need a way to inject the code where it belongs rather than adding it and bogging down the rest of your site with unnecessary HTTPS requests.

So, you should create a separate JavaScript file.

The WordPress Codex includes some steps on what to do with your file next. For easy reference, here is what is recommended:

Whether you have one script or multiple scripts, make sure to define the function for each within the file. For example:

Then, call on the file from the header of your website using a script like this (you can add this to the header using a plugin):

Finally, you’ll need to call on the actual JavaScript function that you defined in the file. Even if there is only one script in there, it needs to be defined in your code.

If the JavaScript applies to the entire page or site, you can add the following JavaScript call to the header. If the JavaScript needs to be executed somewhere on the page, it needs to go within the body of your site:

Rule #4: Use a WordPress Plugin

Thank goodness for WordPress plugins. When it comes to JavaScript, the following plugins will help you circumvent the issues that arise when JavaScript is placed directly into your WordPress files. Instead, these plugins let your server know to call on the script only when the action is “fired”, which helps you get around WordPress theme and plugin updates which will erase any changes you apply directly to them.

Insert Headers and Footers Plugin


This WordPress plugin was developed by WP Beginner to help developers more easily insert custom code into the headers and footers of their themes. Essentially, what it does is give you a convenient tool–outside of the header.php file–where you can add all your custom scripts. Just be aware that this plugin is only ideal if you’re trying to make site-wide changes with JavaScript.

While there are a couple other headers-and-footers plugins available in the WordPress repository, this one from WP Beginner is by far the most popular and trusted of the bunch.

More Information

Shortcoder Plugin


For those of you that want to add custom JavaScript to individual pages or posts, I’ve mentioned a number of ways in which you can do this above. You can add it directly to the HTML if it’s a small script. You can also call on a JavaScript file that holds all your code. Both of those methods, however, still add a number of lines of code to your site and it can make things messier and more difficult to read. If you’d like to clean it up, you can use the Shortcoder plugin.

An added benefit of using Shortcoder is the time-saving factor. Let’s say you have a specific JavaScript function you want to apply to about a dozen or so pages. There’s no need then to copy the script onto each one. Instead, you can create one shortcode to represent that function and insert it whenever you need to.

More Information

Wrapping Up

Understanding how to use JavaScript to bolster the power of your WordPress’s themes, plugins, and content is an incredibly powerful tool to have in your WordPress development arsenal. However, you must be careful in how you use it so as not to disrupt your site’s performance or cause issues with other integrations you’re trying to run on your site. Stick to the rules above, and you should do just fine.

Brenda Barron
Over to you: How long have you been using JavaScript and do you find that it’s needed for every website you build?