Uncaught ReferenceError: jQuery is not defined - Magento 2.3

Uncaught ReferenceError: jQuery is not defined - Magento 2.3

August 19, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Uncaught ReferenceError: jQuery is not defined - Magento 2.3

Solving “Uncaught ReferenceError: jQuery is not defined” in Magento 2.3

When working with third-party extensions or custom JavaScript files in Magento 2.3, you may encounter the dreaded “Uncaught ReferenceError: jQuery is not defined” error message. This issue often arises when trying to include libraries like fancybox that depend on jQuery.

Understanding the Problem

The core problem lies in how Magento manages its JavaScript dependencies and their loading order. By default, Magento loads all necessary scripts after the page has finished rendering, which can lead to timing issues with external libraries.

In your case, you’re trying to use fancybox with Infortis Ultimo theme, but the theme’s scripts haven’t loaded jQuery before your custom JavaScript file attempts to initialize it. This results in the “jQuery is not defined” error and subsequent TypeErrors when fancybox can’t find its initialization function.

Step-by-Step Solution

To resolve this issue, we need to ensure that jQuery is fully loaded before our custom scripts try to access it. Magento provides a built-in mechanism for managing dependencies called RequireJS. Here’s how to use it effectively:

  1. Understand the default_head_blocks.xml file

You’re already using this file correctly by including your custom.js script with the <link src="js/custom.js"/> tag. This ensures that the script gets loaded on every page.

  1. Optimize RequireJS configuration

The key to solving your problem is properly configuring the dependencies in your custom.js file. You’ve already started this process by requiring jQuery, fancybox, and the domReady! plugin:

require(['jquery', 'fancybox', 'domReady!'], function($, fancybox, doc) {
    // Your initialization code here
});

However, you’re missing a crucial step: informing Magento that your script requires these dependencies. To do this, add the following configuration to your default_head_blocks.xml file:

<referenceContainer name="head.additional">
  <block class="Magento\Framework\View\Element\Js\Config" name="requirejs-config">
    <arguments>
      <argument name="modules" xsi:type="array">
        <item name="custom_module-js" xsi:type="array">
          <item name="depends" xsi:type="string">jquery</item>
        </item>
      </argument>
    </arguments>
  </block>
</referenceContainer>

Replace custom_module with the actual module where your JavaScript file is located. This tells Magento that your custom.js script depends on jQuery.

  1. Refactor your initialization code

In your current code, you’re trying to initialize fancybox before the page has fully loaded:

fancyboxExample.init();

This can cause issues if the page isn’t ready when this line executes. To ensure everything is loaded correctly, wrap your initialization code inside a domReady callback:

require(['jquery', 'fancybox', 'domReady!'], function($, fancybox) {
    var fancyboxExample = {
        openModal: function() {
            $.fancybox.open(this.$modal);
        },
        closeModal: function() {
            $.fancybox.close(true);
        }
    };
    document.addEventListener('DOMContentLoaded', function() {
        fancyboxExample.init();
    });
});

By using document.addEventListener('DOMContentLoaded'), you ensure that your initialization code only runs after the entire page, including all scripts, has finished loading.

Conclusion

Resolving the “Uncaught ReferenceError: jQuery is not defined” error in Magento 2.3 requires a proper understanding of how Magento manages its JavaScript dependencies and the correct usage of RequireJS.

Follow these steps to ensure that your custom scripts always have access to required libraries:

  1. Configure your dependencies in both default_head_blocks.xml and custom.js.
  2. Use domReady! plugin to delay initialization until after the page is fully loaded.
  3. Test your changes thoroughly on different pages and devices.

Remember, Magento’s JavaScript ecosystem can be complex, but with careful management of dependencies and proper configuration, you can avoid common errors like these.

For more advanced customizations in Magento, consider checking out Laravel Company’s expertise in Magento development services. Our team specializes in handling complex project requirements and ensuring optimal performance for your eCommerce platform.

Happy coding!

Magento 2 Database Performance Extensions

Our network