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.
