What if you need to replace theme’s JavaScript file with your own custom version of the script?

In WordPress child theme you have an easy way to replace page template from theme or plugin with your own custom version by just creating a file with the same name in your theme’s folder. But that doesn’t work with styles and JavaScripts. While styles are easier to handle (you can just overwrite styles in your own CSS file, just make sure it’s called after the original file), it’s a bit more complicated with JavaScript code.

First of all, ask yourself a question. Do you really need to replace that JavaScript file? In most cases you don’t. If you adding some custom functionality or events handling, you can just do it in your own file, which you add to your child theme and load with wp_enqueue_script() function. But in some situations, you really have to remove the original script and replace it with your own.

My Use Case / Example

I was setting up a site based on “Listable” theme, which uses “WP Job Manager” plugin. That plugin comes with AJAX filters for listings search. I wanted to have my own filters, which is easy to override using partial page template, but original JavaScript code is very particular about what fields you can use in that dynamic listings filter. So, my extra fields were just ignored. It did not make sense to keep original ajax-filters.min.js file used by plugin, as most of the code in that file won’t work for me (and potentially mess things up).

Solution: how to replace theme’s JavaScript file with your own version.

I assume that the theme uses wp_enqueue_script() function to call JavaScript file (which is the correct way to include JavaScript and most themes and plugins follow this standard).

Step 1: Create your custom JavaScript file

Let’s start with creating your own JavaScript file. Use one from the theme as a starter if you making modifications, or, create a blank file if you are starting from scratch. Upload the file into your child theme’s folder, in my example, I placed it in js/ajax-filters.js

Step 2: Find the “Handle” of JavaScript file

You will need to know the “handle” of the file you want to remove. There are 2 ways to find it.

• Search theme and/or plugin source code, use script filename as a search keyword. In my case it was “ajax-filters.min.js”. After running the search on WP Job Manager plugin I found this line of code

  wp_register_script( 'wp-job-manager-ajax-filters',
      JOB_MANAGER_PLUGIN_URL . '/assets/js/ajax-filters.min.js',
      $ajax_filter_deps,
      JOB_MANAGER_VERSION,
      true );
  

  It could be wp_register_script() or wp_enqueue_script() function call and the first argument ‘wp-job-manager-ajax-filters’ is the handle of my JavaScript file. Handle is unique reference to that file, which WordPress uses internally.

• If search did not produce any results, you can print out all registered scripts and find one you need by adding the following code to your child theme’s functions.php file:

  function customwp_assets() {
      global $wp_scripts;
      echo "\n<!-- REGISTERED SCRIPTS \n"; 
      foreach( $wp_scripts->registered as $handle => $script) :
          echo $handle,":",$script["src"],"\n";
      endforeach;
      echo "\n-->";
  }
  add_action('wp_enqueue_scripts', 'customwp_assets', 10000);
  

  Now open WordPress page (where the script is used) and view source. Look for “REGISTERED SCRIPTS” and you will see something like this:

  <!-- REGISTERED SCRIPTS 
  utils:/wp-includes/js/utils.min.js
  common:/wp-admin/js/common.min.js
  ...
  wp-job-manager-ajax-filters:http://.../js/ajax-filters.min.js
  

  Here is our script’s handle “wp-job-manager-ajax-filters”! Don’t forget to remove that code from functions.php 😉

Step 3: Replace theme’s JavaScript with your custom version

Once we know the handle we can de-register script and register custom js script in it’s place using the same handle. Here is the code which I used to replace it with my own “js/ajax-filters.js” in the child-theme’s folder:

function customwp_assets() {
    wp_deregister_script('wp-job-manager-ajax-filters');
    wp_register_script( 'wp-job-manager-ajax-filters',
        get_stylesheet_directory_uri().'/js/ajax-filters.js',
        array( 'jquery'),
        JOB_MANAGER_VERSION,
        true );
}
add_action('wp_enqueue_scripts', 'customwp_assets', 10000);