Enqueue scripts/styles the right way (with dependencies)

Enqueue Scripts/Styles the Right Way (with Dependencies)

Properly enqueueing scripts and styles in WordPress is essential for ensuring your site loads efficiently, avoids conflicts, and respects dependencies. This tutorial explains how to enqueue scripts and styles the right way, including managing dependencies, and provides practical code examples you can copy and paste into your theme or plugin.

When to Use Proper Enqueueing

• Adding custom JavaScript or CSS to your theme or plugin.
• Loading third-party libraries like jQuery, Bootstrap, or Font Awesome.
• Ensuring scripts/styles load only when needed to optimize performance.
• Preventing conflicts by managing script dependencies and versions.

Quick Fix: Enqueue Scripts Properly in WordPress

1. Use wp_enqueue_script() and wp_enqueue_style() functions.
2. Hook your enqueue functions to wp_enqueue_scripts (frontend) or admin_enqueue_scripts (admin area).
3. Specify dependencies as an array to ensure correct load order.
4. Use versioning to bust cache when files update.
5. Place your enqueue code in functions.php or a custom plugin.

Why This Happens

WordPress uses a queue system to manage scripts and styles. If you add scripts/styles incorrectly (e.g., hardcoding in header/footer), you risk:

• Loading scripts multiple times or out of order.
• Conflicts between plugins or themes using the same libraries.
• Broken dependencies causing JavaScript errors.
• Performance issues due to unnecessary or duplicated loads.

Using WordPress’s enqueue functions ensures scripts and styles load once, in the right order, and only when needed.

Step-by-Step: Enqueue Scripts and Styles with Dependencies

Below is a complete example showing how to enqueue a custom JavaScript file and a CSS file with dependencies on jQuery and a third-party CSS library.

<?php
function mytheme_enqueue_assets() {
    // Enqueue a CSS library (e.g., Bootstrap) from CDN
    wp_enqueue_style(
        'bootstrap-css', // Handle
        'https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css', // Source
        array(), // No dependencies
        '5.3.0' // Version
    );

    // Enqueue a custom stylesheet that depends on Bootstrap CSS
    wp_enqueue_style(
        'mytheme-style',
        get_template_directory_uri() . '/css/custom-style.css',
        array('bootstrap-css'), // Dependency
        '1.0.0'
    );

    // Enqueue jQuery (WordPress includes jQuery by default)
    wp_enqueue_script('jquery');

    // Enqueue a custom JavaScript file that depends on jQuery
    wp_enqueue_script(
        'mytheme-script',
        get_template_directory_uri() . '/js/custom-script.js',
        array('jquery'), // Dependency
        '1.0.0',
        true // Load in footer
    );
}
add_action('wp_enqueue_scripts', 'mytheme_enqueue_assets');
?>

Explanation:

• wp_enqueue_style() loads CSS files. The third parameter is an array of dependencies.
• wp_enqueue_script() loads JavaScript files. The third parameter is dependencies, the fourth is version, and the fifth controls whether to load in footer.
• Using get_template_directory_uri() points to your theme folder.
• Hooking into wp_enqueue_scripts ensures scripts/styles load on the frontend.

Add via functions.php or Mini-Plugin

You can add the above code directly to your theme’s functions.php file or create a mini-plugin for portability.

<?php
/*
Plugin Name: My Custom Enqueue Plugin
Description: Properly enqueue scripts and styles with dependencies.
Version: 1.0
Author: Your Name
*/

function myplugin_enqueue_assets() {
    wp_enqueue_style('bootstrap-css', 'https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css', array(), '5.3.0');
    wp_enqueue_style('myplugin-style', plugin_dir_url(__FILE__) . 'css/custom-style.css', array('bootstrap-css'), '1.0.0');
    wp_enqueue_script('jquery');
    wp_enqueue_script('myplugin-script', plugin_dir_url(__FILE__) . 'js/custom-script.js', array('jquery'), '1.0.0', true);
}
add_action('wp_enqueue_scripts', 'myplugin_enqueue_assets');
?>

Testing Your Enqueued Scripts and Styles

1. Clear your browser cache or use incognito mode.
2. View your site’s source code (Ctrl+U or right-click → View Page Source).
3. Search for your script and style handles (e.g., mytheme-style or mytheme-script).
4. Check the order of scripts/styles to confirm dependencies load first.
5. Open browser developer tools (Console tab) to ensure no JavaScript errors.

Variations

if (is_page('contact')) {
    wp_enqueue_script('contact-form', ...);
}

add_action('admin_enqueue_scripts', 'my_admin_assets');
function my_admin_assets() {
    wp_enqueue_style('admin-style', ...);
}

wp_localize_script('mytheme-script', 'myData', array(
    'ajaxUrl' => admin_url('admin-ajax.php'),
));

Works On

• Web servers: Apache, Nginx, LiteSpeed