How to Load JavaScript and CSS in a WordPress Plugin

When a WordPress plugin adds a feature to a page, the browser needs the plugin’s JavaScript and CSS files. WordPress’s enqueue functions let plugin code ask WordPress to add those files to the generated page at the right time. WordPress tracks each file by name and handles its dependencies. It also avoids adding the same registered file more than once.

Use wp_enqueue_script() for JavaScript and wp_enqueue_style() for CSS. Call these functions from a WordPress action hook, a point in a page request when WordPress runs plugin code. The example below shows how to load files from your plugin, limit them to pages that need them, and set versions so browsers notice updates.

Enqueue plugin files from a WordPress hook

Add an enqueue function to your plugin and connect it to wp_enqueue_scripts, the hook WordPress uses to load front-end files. A handle is the unique name WordPress uses to identify a file. Give each handle a plugin-specific prefix so another plugin is less likely to use the same name.

add_action( 'wp_enqueue_scripts', 'acme_enqueue_public_assets' );

function acme_enqueue_public_assets() {
    $css_file = plugin_dir_path( __FILE__ ) . 'assets/css/plugin.css';
    $js_file  = plugin_dir_path( __FILE__ ) . 'assets/js/plugin.js';

    wp_enqueue_style(
        'acme-plugin',
        plugins_url( 'assets/css/plugin.css', __FILE__ ),
        array(),
        filemtime( $css_file )
    );

    wp_enqueue_script(
        'acme-plugin',
        plugins_url( 'assets/js/plugin.js', __FILE__ ),
        array(),
        filemtime( $js_file ),
        array( 'strategy' => 'defer' )
    );
}

Put this code in the plugin file used to build the paths, and create the two files in the matching locations. plugins_url() builds their URLs from the plugin’s location. WordPress recommends wp_enqueue_script() for adding JavaScript to a generated page. The wp_enqueue_style() function adds a stylesheet. WordPress’s script function reference explains the JavaScript parameters, and a CSS enqueue example shows how to use the stylesheet function.

The empty dependency arrays tell WordPress that these files have no declared dependencies. If your JavaScript needs a WordPress-registered script such as jQuery, put that script’s handle in the dependency array. WordPress uses the dependencies to determine the order in which scripts load.

The last argument to wp_enqueue_script() sets how the browser loads the script. WordPress supports defer and async strategies in this argument as of version 6.3. A deferred script runs after the browser parses the page’s HTML and before it fires DOMContentLoaded. Deferred scripts keep their order. An asynchronous script runs as soon as it finishes downloading, and its order is not guaranteed. Choose defer when the script needs the page markup or must run in order with another script. Omit the strategy if your plugin must support WordPress versions before 6.3.

The example uses each file’s modification time as its version. When you update a file, its version changes, so browsers request the updated file instead of using a cached copy. Do not use a value that changes on every request, such as microtime(), because browsers then cannot reuse cached files.

Load assets only where the feature appears

The example above loads both files on every front-end page. To load them only on a particular page, put the enqueue calls inside a WordPress conditional check:

function acme_enqueue_public_assets() {
    if ( ! is_page( 'contact' ) ) {
        return;
    }

    $css_file = plugin_dir_path( __FILE__ ) . 'assets/css/plugin.css';
    $js_file  = plugin_dir_path( __FILE__ ) . 'assets/js/plugin.js';

    wp_enqueue_style(
        'acme-plugin',
        plugins_url( 'assets/css/plugin.css', __FILE__ ),
        array(),
        filemtime( $css_file )
    );

    wp_enqueue_script(
        'acme-plugin',
        plugins_url( 'assets/js/plugin.js', __FILE__ ),
        array(),
        filemtime( $js_file ),
        array( 'strategy' => 'defer' )
    );
}

Here, is_page( 'contact' ) checks whether the current page has the contact slug. Replace this check with one that matches where your plugin feature appears. For example, WordPress conditional tags can target other page types. If the feature appears only when a page contains a shortcode or block, use a condition that identifies those pages. Checking the page slug alone does not detect shortcode or block content.

Use admin_enqueue_scripts for files used in the WordPress administration area, and login_enqueue_scripts for files used on the login screen. Load each file only on the hook and pages where it belongs to avoid adding front-end files to unrelated admin screens.

Add inline code to an enqueued asset

When a short style or script needs a plugin file, attach it to that file’s handle instead of printing it directly into the page. wp_add_inline_style() adds CSS after an enqueued stylesheet. wp_add_inline_script() attaches JavaScript to a registered script. WordPress prints the inline code only if that script is also in the queue.

wp_add_inline_style(
    'acme-plugin',
    '.acme-widget { display: block; }'
);

wp_add_inline_script(
    'acme-plugin',
    'console.log("Plugin script loaded");'
);

Pass JavaScript code without <script> tags. Use the same handle you used to enqueue the file. WordPress will not add the inline code if the handle is missing or the associated script is not in the queue.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com