jQuery in WordPress

WordPress already includes jQuery; current versions ship jQuery 3.7. There is no need to load the library from a CDN: just tell WordPress that your script needs jQuery, and it loads it once, in the right order.

Where the files live

The script goes into the theme folder and is registered in the theme's functions.php:

wp-content/themes/my-theme/
├── functions.php
├── style.css
└── js/
    └── todo.js

If you are changing someone else's theme, create a child theme: otherwise your files disappear when the parent theme updates.

Loading: wp_enqueue_script

Add to functions.php:

<?php
// wp-content/themes/my-theme/functions.php
 
function my_theme_scripts() {
    wp_enqueue_script(
        'my-theme-todo',                 // script handle
        get_theme_file_uri('js/todo.js'), // file URL
        array('jquery'),                 // dependencies
        '1.0.0',                         // version
        true                             // load at the end of the page
    );
}
add_action('wp_enqueue_scripts', 'my_theme_scripts');

wp_enqueue_script() puts the script in the queue. The 'jquery' dependency guarantees jQuery loads before your file. The version is added to the URL as ?ver=1.0.0, so when it changes the browser does not use the old cached file. Open any page of the site and view its source: a tag with jquery.min.js comes before todo.js.

noConflict mode

WordPress loads jQuery in noConflict mode: the short name $ is left free for other libraries, and only the full name jQuery is available. That is why familiar code fails in WordPress with $ is not a function.

The fix is to receive $ as an argument. A function passed to jQuery() gets jQuery itself as its first argument:

// wp-content/themes/my-theme/js/todo.js
jQuery(function ($) {
  $('.todo-list').on('click', 'li', function () {
    $(this).toggleClass('done');
  });
});

Inside the function $ works as usual again, and outside it does not get in the way of other scripts. The same technique, the (function ($) { ... })(jQuery) wrapper, is used in plugins from the previous lesson.

Markup

The list is output in a theme template such as page.php, or through a "Custom HTML" block in the editor:

<ul class="todo-list">
  <li>Buy bread</li>
  <li>Call Oleg</li>
</ul>

Clicking an item on the site crosses it out, provided the theme's style.css has a rule for the done class.

noConflict outside WordPress

Outside WordPress this mode is turned on manually:

// script.js
const jq = jQuery.noConflict();
jq('h1').text('To-do list');

After the call $ goes back to the library that held it before jQuery, and jQuery is available as jQuery and jq.

Common mistake

Removing the built-in jQuery with wp_deregister_script('jquery') and loading your own from a CDN or in another version. WordPress plugins are built for the bundled version and may stop working, and a typo in the URL removes jQuery from the whole site. Use the one that ships with WordPress.