Magento 2 - Extend onepage.phtml to add custom JS

Magento 2 - Extend onepage.phtml to add custom JS

August 20, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Magento 2 - Extend onepage.phtml to add custom JS

Extending Magento 2: Adding Custom JS to the Checkout Page

Magento 2 is a powerful e-commerce platform that allows for extensive customization. In this post, we’ll guide you through adding custom JavaScript (JS) to the checkout page where the shipping address and method are set.

Understanding the Current Setup

You’ve already made great progress by creating a custom module and attempting to extend the onepage.phtml template. Here’s what you have so far:

  1. Created a custom onepage template: My_Module\view\frontend\templates\onepage.phtml
  2. Defined layout updates in checkout_index_index.xml: My_Module\view\frontend\layout\checkout_index_index.xml
  3. Placed your JavaScript file at My_Module\view\frontend\web\js\custom.js

Your current configuration looks promising. However, you’re facing issues with the JS not being loaded correctly.

Identifying the Problem

Let’s analyze where things might be going wrong:

  1. Your <script> tag is properly included in the onepage.phtml file.
  2. The requirejs-config.js file maps your custom JavaScript to the correct path.
  3. The checkout_index_index.xml file correctly references the new onepage template.

The primary issue seems to be with how you’re using the referenceBlock and its name attribute in the XML layout update file.

Resolving the Issue: A Step-by-Step Approach

1. Use the Correct Reference Block Name

The checkout.onepage block corresponds specifically to the onepage checkout process. In your case, you’re trying to render a custom template for this specific context. Therefore, using checkout.root as suggested in your question isn’t accurate.

Stick with checkout.onepage, and ensure the XML layout update file is correctly configured:

<referenceBlock name="checkout.onepage">
    <action method="setTemplate">
        <argument name="template" xsi:type="string">My_Module::onepage.phtml</argument>
    </action>
</referenceBlock>

2. Ensure the JavaScript File is Properly Configured

Check that your custom.js file follows these conventions:

  • The file should be located in the correct path: My_Module\view\frontend\web\js\custom.js
  • It should contain valid JavaScript code.
  • It shouldn’t have any syntax errors or conflicts with other JS files.

3. Verify the File Paths

Ensure that all your file paths match the following structure:

  • Module name: My_Module
  • View type: frontend
  • Template/JS directory: view\frontend\web\js (or templates for PHP templates)

4. Check for Typos and Spelling Mistakes

Double-check your XML configuration files (checkout_index_index.xml) for any typos or incorrect namespace declarations.

A Better Approach: Using Magento’s JS Mixin System

As an alternative to using the onepage.phtml, you might want to consider using Magento’s built-in JavaScript mixins. This approach allows you to inject custom JavaScript logic into existing scripts without touching the core templates.

To learn more about this method, check out our detailed guide on Extending Magento 2 with Custom JS Mixins.

Conclusion

Adding custom JavaScript to the checkout page in Magento 2 requires a careful understanding of the platform’s template system and layout updates. By using the correct reference block name, verifying file paths, and ensuring proper configuration, you can successfully extend the onepage.phtml template with your own JS scripts.

Remember to always test your changes thoroughly and backup your data before making significant modifications to your Magento installation.

Happy coding! If you have any further questions or need more detailed assistance, feel free to reach out. We’re here to help!

Magento 2 Checkout Extensions Themes

Our network