Use custom JavaScript

Overview

This topic discusses about how to use custom JavaScript components with the components provided by Magento or having replaced them with custom implementations.

We strongly recommend not changing the source code of default Magento components and widgets. All customizations must be implemented in custom modules or themes.

Replace a default JS component

To use a custom implementation of an existing Magento JS component:

1. Place the custom component source file in one of the following locations:
   • Your theme JS files: <theme_dir>/web/js
   • Your module view JS files: <module_dir>/view/frontend/web/js
2. Create a RequireJS configuration file requirejs-config.js, having specified the following:

   var config = {
     "map": {
       "*": {
         "<custom_component>": "<default_component>"
       }
     }
   };

   Where the following notation is used:
   • <default_component>: the name of the default component you replace
   • <custom_component>: the name of the custom component
   For example, if you want to use custom navigation-menu.js script instead of the default menu widgets, your requirejs-config.js should contain the following:

   var config = {
     "map": {
       "*": {
         "menu": "js/navigation-menu",
         "mage/backend/menu": "js/navigation-menu",
       }
     }
   };

3. Place your requirejs-config.js file in one of the following directories (according to the location of your custom script, see step 1 of this procedure):
   • Your theme files: <theme_dir>
   • Your module view files: <module_dir>/view/frontend

This way your custom JS component is used instead of the Magento component in all entries all over the frontend area.

Extend a default JS component

You can add a custom JS component/widget, which will extend a default Magento component/widget.

Extend Magento widget

To extend a default Magento jQuery widget, create <your_widget_name>.js with the following contents:

define([
  'jquery',
  'jquery/ui',
  'mage/<widget.name>' // usually widget can be found in /lib/web/mage dir
], function($){
 
  $.widget('<your_namespace>.<your_widget_name>', $.mage.<widget.name>, { ... });
 
  return $.<your_namespace>.<your_widget_name>;
});

Where the following notation is used:

• <your_namespace>.<your_widget_name> - the name of your custom widget. According to the jQuery widgets naming convention, must contain a namespace and name.
• mage.<widget.name> - the name of the Magento widget that you extend.

For information about how to initialize your custom widget in a .phtml template, see the JavaScript initialization topic.

Extend a default Ui component

To extend a default JS Ui component, your custom script must contain the following:

define([
  '<component_path>'
], function(<component_alias>){
 
  return <component_alias>.extend({
 
    defaults: { ... }, // properties with default values
    ... // methods of your component
  });
});

Where the following notation is used:

• <component_path>: path to the default component that you extend
• <component_alias>: variable containing the default component that you extend

For example, Filters.js script extends the default filters.js:

define([
  'Magento_Ui/js/grid/filters/filters'
], function(Filters){
 
  return Filters.extend({
 
    defaults: { ... }, // properties with default values
    ... // methods of your component
  });
});

For information about how to initialize your custom JS component in a .phtml template, see the JavaScript initialization topic.

Disable default Magento JS

To disable the auto-loading of default Magento JS components and widget initialization:

1. Create a requirejs-config.js file with the following content:

   var config = {
       deps: [
       ]
   };

2. Put the requirejs-config.js file in one of the following locations:
   • Your custom theme files: <theme_dir>
   • Your custom module files: <module_dir>/view/frontend

If you need to enable the loading of default Magento JS components and widget initialization on a certain stage, add the following code in your JS script:

$(mage.apply);

Related topics

JavaScript resources configuration