How to use wp_enqueue_script() to load JavaScript files in WordPress

Jul 27, 2019

In the early days in my career as a WordPress dev I used to load my JavaScript files like this:

<script src="<?php site_url(); ?>/wp-conteht/themename/dist/main.js"></script>

This was simple and easy to understand. While this obviously works, I later discovered that there is a better way to enqueue scripts built in WordPress core. In this article I’m going to show you how, why and when you should use wp_enqueue_script() to load your JavaScript files.

The basics

To understand fully how wp_enqueue_script() works we should take a look at the wp_head() and wp_footer() functions. They’re used placed into your header.php and footer.php in a way that those files combined would look like this:

<!doctype html>
<html>
<head>
	<?php wp_head(); ?>
</head>
<body>
	<div class="main"></div>
	<footer class="main-footer"></footer>
	<?php wp_footer(); ?>
</body>

wp_head() and wp_footer() are basically places where you can echo things through wp_head and wp_footer hooks. So for an example this:

<?php

// functions.php

function hello_world_comment() {
	echo "<!-- Hello world -->"
}

add_action( 'wp_head', 'hello_world_comment', 100 );

would echo <!-- Hello world --> to the place where you call the wp_head()function.

And you could definitely do something like this:

<?php

// functions.php

function main_js_to_wp_footer() {
	echo '<script src="' . site_url(); . '/wp-conteht/themename/dist/main.js"></script>';
}

add_action( 'wp_footer', 'main_js_to_wp_footer', 100 );

But there’s still a better way to enqueue scripts into your WordPress theme.

wp_enqueue_script()

wp_enqueue_script() works as an additional layer for these wp_head and wp_footerfilters. The main benefits for using wp_enqueue_script() are:

  • You can set dependencies for the scripts you load, so for example you could add jquery as a dependency for your main.js (not covered in this post)
  • You can use wp_localize_script to pass data from PHP to JavaScript (see here for more information)

wp_enqueue_script() works like this:

<?php

// functions.php

function wpa_enqueue_scripts() {
	wp_enqueue_script( 'wpa-main-js', get_theme_file_uri( 'dist/scripts/main.js' ), [], null, true );
}

add_action( 'wp_enqueue_scripts', 'wpa_enqueue_scripts', 100 );

and it outputs something like this into your wp_footer():

<script src="https://www.example.com/wp-conteht/themename/dist/main.js"></script>

and take a note that we’re using the wp_enqueue_scripts hook here, which loads the script into your theme. You can use the admin_enqueue_scripts hook if you would like to enqueue a script into wp-admin.

The most interesting parts in that wp_enqueue_script() call is the first parameter ('wpa-main-js') and the last parameter (true).

The first parameter is a handle, which you can think as a nickname for the JavaScript file. Handle is being used when you want to add something as a dependency for your enqueue. For example you could pass ['jquery'] into your dependencies if you’re using jquery in the file you’re trying to enqueue. Or you can enqueue a file with a handle 'first' and then use it as a dependency for your second file called 'second' like this:

<?php

// functions.php

function wpa_enqueue_scripts() {
	wp_enqueue_script( 'first', get_theme_file_uri( 'dist/scripts/first.js' ), [], null, true );
wp_enqueue_script( 'second', get_theme_file_uri( 'dist/scripts/main.js' ), ['first'], null, true );
}

add_action( 'wp_enqueue_scripts', 'wpa_enqueue_scripts', 100 );

The last parameter decides if the JavaScript file should be enqueued in wp_head() or in wp_footer(). False means header and true means footer.

Helpful tips

Cache busting

Browsers are caching now external loads pretty heavily, so it’s wise to have some kind of a method for busting cache. Luckily it’s pretty easy to bust a cache with the timestamp of the js file:

<?php

// functions.php

function wpa_enqueue_scripts() {
	wp_enqueue_script( 'wpa-main-js', get_theme_file_uri( 'dist/scripts/main.js' ), [], filemtime( get_theme_file_path( 'dist/scripts/main.js' ) ), true );
}

add_action( 'wp_enqueue_scripts', 'wpa_enqueue_scripts', 100 );

Use wp_enqueue_style() for css files

There’s actually almost identical function to wp_enqueue_script() called wp_enqueue_style() that allows you to enqueue css files. A quick example:

<?php

// functions.php

function wpa_enqueue_styles() {
	wp_enqueue_style( 'wpa-main-css', get_theme_file_uri( 'dist/styles/main.css' ), [], filemtime( get_theme_file_path( 'dist/styles/main.css' ) ) );
}

add_action( 'wp_enqueue_scripts', 'wpa_enqueue_scripts', 100 );

That should be pretty much all the information you’d need to have to start using wp_enqueue_script() function.

If you’re interested in how to pass data for the JavaScript files enqueued with wp_enqueue_script(), please see this post.