Skip to content

Defer JavaScript

Add the defer attribute to enqueued scripts for faster page rendering and improved Time to Interactive.

How It Works

The defer attribute tells the browser to download the script in parallel with HTML parsing but delay execution until the HTML is fully parsed. This prevents scripts from blocking the initial page render.

<!-- Without defer: blocks rendering -->
<script src="plugin.js"></script>

<!-- With defer: non-blocking -->
<script defer src="plugin.js"></script>

What Gets Deferred

All frontend scripts registered via wp_enqueue_script() that have a src attribute.

Automatic Exclusions

Some scripts cannot be deferred without breaking functionality:

Script Reason
jQuery Core Inline scripts depend on jQuery being available immediately
jQuery Migrate Depends on jQuery, same reason
ES Modules (type="module") Already deferred by specification
Scripts with data-cfasync="false" Explicitly marked as non-deferrable
Inline scripts (no src) Cannot be deferred

Custom Exclusions

If a specific script breaks when deferred, add its handle to the exclusion list:

  1. Go to Cacheability Pro > Page Optimization
  2. Open Advanced Settings
  3. Add the script handle (one per line) to Defer JS Exclusions

To find a script's handle, inspect the HTML source. WordPress adds an id attribute with the format {handle}-js:

<script defer src="..." id="my-plugin-script-js"></script>
<!-- Handle: my-plugin-script -->

Admin Scripts

Scripts on WordPress admin pages are never deferred to avoid breaking the admin UI.

Performance Impact

Deferring scripts typically improves:

  • First Contentful Paint (FCP) - content appears sooner
  • Time to Interactive (TTI) - page becomes interactive faster
  • Lighthouse Performance Score - directly measured by Lighthouse