Table of contents

Understanding wp_enqueue_scripts Basic usage Local JavaScript files External scripts JavaScript conditionally Enqueueing scripts with dependencies Load scripts Adding version control How to debug FAQs Getting started

Get the industry’s fastest WordPress hosting ◦ 99.99% uptime
◦ Comprehensive security
◦ 24/7 support

WordPress Guide → Development → Enqueue Scripts

How to enqueue scripts using wp_enqueue_scripts

If you’ve ever copied a <script> tag directly into your WordPress theme’s header or footer file, stop right there. WordPress has a better way.

To load JavaScript files the right way—and avoid conflicts, duplicate loading, or performance issues—you should use wp_enqueue_script. Let’s walk through how it works, when to use it, and how to make sure your scripts are loaded exactly where and when you need them.

Get fast, reliable hosting for WordPress

Power your site with the industry’s fastest, most optimized WordPress hosting

WordPress.org hosting

Understanding wp_enqueue_scripts in WordPress

Polyfills are JavaScript files that mimic modern browser features in older browsers. WordPress includes a built-in polyfill script (wp-polyfill) to ensure compatibility with outdated environments—especially browsers that don’t support features like Promise, Array.prototype.includes, or Object.assign.

This function should go inside your theme’s functions.php file or inside a plugin. For admin area scripts, you’d use a separate hook called admin_enqueue_scripts.

Basic usage of wp_enqueue_script

At its core, wp_enqueue_script looks like this:

function mytheme_enqueue_scripts() {     wp_enqueue_script('custom-script', get_template_directory_uri() . '/js/custom.js', array(), '1.0', true); } add_action('wp_enqueue_scripts', 'mytheme_enqueue_scripts');

Here’s what each parameter means:

‘custom-script’ is the handle, a unique name for the script.
The second parameter is the URL to the script file.
The third parameter is an array of dependencies (like [‘jquery’]).
‘1.0’ is the version number, used for cache busting.
true loads the script in the footer. Set it to false to load in the header.

How to enqueue local JavaScript files

For scripts stored in your theme folder, use get_template_directory_uri() (for parent themes) or get_stylesheet_directory_uri() (for child themes):

wp_enqueue_script('main', get_template_directory_uri() . '/js/main.js', array(), '1.0', true);

Good practices:

Wrap your enqueue call inside a function.
Always hook into wp_enqueue_scripts.
Use versioning or filemtime() to avoid browser cache issues.

How to enqueue external scripts (like CDNs)

To load a script from a CDN, just use the direct URL in place of the file path:

wp_enqueue_script('jquery-cdn', 'https://code.jquery.com/jquery-3.6.0.min.js', array(), null, true);

Only do this if you need a different version than the one WordPress provides. If you’re using built-in jQuery, you can enqueue it like this:

wp_enqueue_script('jquery');

How to enqueue JavaScript conditionally

Want to load a script only on your contact page? Use conditional logic:

function contact_scripts() {     if (is_page('contact')) {         wp_enqueue_script('contact-js', get_template_directory_uri() . '/js/contact.js', array(), '1.0', true);     } } add_action('wp_enqueue_scripts', 'contact_scripts');

This improves performance by only loading what you need.

Enqueueing scripts with dependencies

You can load scripts in a specific order by setting dependencies. For example:

wp_enqueue_script('slider', get_template_directory_uri() . '/js/slider.js', array('jquery'), '1.0', true);

WordPress knows to load jQuery first. Common built-in dependencies include:

jquery
jquery-ui-core
wp-element (for React)
wp-api-fetch (for REST API calls)

How to load scripts in the WordPress admin

For backend admin pages, use the admin_enqueue_scripts hook. You can even check for specific admin pages using the $hook parameter:

function my_admin_scripts($hook) {     if ($hook !== 'toplevel_page_my_plugin') {         return;     }     wp_enqueue_script('admin-js', plugin_dir_url(__FILE__) . 'admin.js', array(), '1.0', true); } add_action('admin_enqueue_scripts', 'my_admin_scripts');

This ensures your admin script loads only where it’s needed.

Adding version control to avoid browser cache issues

If users report that changes to your script aren’t showing, browser cache is likely to blame. You can use PHP’s filemtime() function to dynamically version your scripts:

$path = get_template_directory() . '/js/custom.js'; $url = get_template_directory_uri() . '/js/custom.js'; wp_enqueue_script('custom', $url, array(), filemtime($path), true);

This changes the version each time the file is updated.

How to debug enqueued scripts in WordPress

Sometimes a script doesn’t load, and you’re left scratching your head. Here’s how to troubleshoot:

Use wp_script_is(‘handle’, ‘enqueued’) to check if it’s been enqueued.
Echo wp_print_scripts() to output all scripts.
Open your browser’s dev tools and look for 404 errors.
Make sure you’re calling wp_enqueue_script before wp_head or wp_footer.
Install Query Monitor to inspect all assets being loaded.

These methods help you confirm whether the script was enqueued and loaded successfully.

wp_enqueue_scripts FAQs

wp_enqueue_script helps load JavaScript files the WordPress way. It ensures your scripts are included only once, loaded in the correct order, and placed in either the header or footer based on performance needs.

wp_register_script lets you register a script for later use without loading it. wp_enqueue_script actually queues it up to load. If needed, you can register a script first and conditionally enqueue it later.

Use wp_enqueue_style like this:

wp_enqueue_style('theme-style', get_stylesheet_uri(), array(), '1.0', 'all');

You can enqueue additional styles from your theme folder or external stylesheets using this function in the same wp_enqueue_scripts hook.

WP Mail SMTP is one of the most popular and reliable SMTP plugins. It supports multiple mailers like Gmail, SendLayer, and SMTP.com. Other good options include Post SMTP and Easy WP SMTP.

Next steps for using wp_enqueue_scripts

Learning how to enqueue scripts the right way is key to building fast, functional, and conflict-free WordPress themes or plugins. It’s one of the first tools any WordPress developer should master.

To take it further, start applying conditional loading and dependency management across your site’s assets. It keeps things clean—and faster for your users.