How to Add Custom JavaScript to WordPress Themes

You want to add custom JavaScript to your WordPress theme. Maybe it’s a scroll effect, a third-party tracking snippet, or interactive functionality. You paste the code into your template file, and nothing works—or worse, you mix PHP and JavaScript together and break everything.

This happens constantly. The fix is straightforward: use WordPress’s built-in script management system instead of hardcoding <script> tags.

Why You Should Enqueue Scripts in WordPress

WordPress runs on a complex ecosystem of themes and plugins. When you insert JavaScript directly into templates, you create problems:

• Duplicate loading: Multiple plugins might load the same library.
• Dependency failures: Your script runs before its dependencies load.
• Caching issues: Browsers can’t properly cache inline scripts.
• Conflicts: Scripts interfere with each other without coordination.

The wp_enqueue_script function solves these problems by letting WordPress manage script loading order, dependencies, and output location.

The Correct Way to Add JavaScript to WordPress

Step 1: Create Your JavaScript File

Place your JavaScript in your theme’s directory. A common structure:

your-theme/
├── js/
│   └── custom.js
├── functions.php
└── style.css

Write clean JavaScript without mixing in PHP:

document.addEventListener('DOMContentLoaded', function() {
    // Your code here
});

Step 2: Enqueue the Script in functions.php

Add this to your theme’s functions.php:

function mytheme_enqueue_scripts() {
    wp_enqueue_script(
        'mytheme-custom',                              // Handle
        get_template_directory_uri() . '/js/custom.js', // Source
        array(),                                        // Dependencies
        '1.0.0',                                        // Version
        array( 'in_footer' => true )                   // Load in footer
    );
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

For child themes, use get_stylesheet_directory_uri() instead of get_template_directory_uri().

Understanding wp_enqueue_script Parameters

The function accepts five parameters:

Conditional Script Loading

Don’t load scripts everywhere when they’re only needed on specific pages:

function mytheme_enqueue_scripts() {
    if ( is_singular( 'post' ) ) {
        wp_enqueue_script( 'mytheme-post-scripts', /* ... */ );
    }

    if ( is_page( 'contact' ) ) {
        wp_enqueue_script( 'mytheme-contact-form', /* ... */ );
    }
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

Performance-Aware Loading Strategies

WordPress 6.3 introduced native support for defer and async loading:

wp_enqueue_script(
    'mytheme-analytics',
    get_template_directory_uri() . '/js/analytics.js',
    array(),
    '1.0.0',
    array(
        'in_footer' => true,
        'strategy'  => 'defer'
    )
);

Defer executes scripts after DOM parsing while maintaining their declared order. Async executes scripts immediately once downloaded, with no guaranteed order. Use defer for most cases and async for independent scripts like analytics.

Modern WordPress: Script Modules and Block Integration

WordPress continues evolving its JavaScript handling. Two developments worth noting:

Script Modules API: WordPress 6.5 introduced wp_enqueue_script_module() for native ES modules. This enables modern JavaScript patterns with proper module imports.

Block-based themes: If you’re building blocks, declare scripts in block.json using the viewScript or viewScriptModule fields rather than manual enqueueing. WordPress handles loading automatically when the block renders.

These approaches work alongside traditional enqueueing—choose based on your project’s needs.

Conclusion

Adding custom JavaScript to WordPress themes requires using the enqueueing system, not hardcoded script tags. Create separate JavaScript files, register them with wp_enqueue_script, declare dependencies properly, and use conditional loading to avoid unnecessary requests. For better performance, leverage the defer and async strategies available since WordPress 6.3.

The pattern is simple: keep PHP and JavaScript separate, let WordPress manage the loading, and your scripts will work reliably across themes and plugins.

FAQs

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.