Magento custom Knockout.js bindings

This topic lists the custom Knockout.js bindings used in the core Magento files. These bindings can also be used by third-party developers.

General concepts

Aliases

The standard way to reference a knockout.js binding is using the data-bind attribute: [data-bind="%binding_name%: %value%"]. In Magento implementation, you can also use aliases to declare bindings. Some bindings may be defined as attributes ([%binding_alias%="%value%"]) or nodes (%binding_alias% args="%value%">).

Binding values

Apart from the value type specified for each binding, every value may be wrapped in Knockout’s observable.

Custom Magento bindings

afterRender

The afterRender binding notifies its subscriber when an associated element is inserted into the DOM.

Source: <Magento_Ui_module_dir>/view/base/web/js/lib/knockout/bindings/after-render.js. See on Github.

Value type: (element: Element, viewModel: Object) => void. Function that is invoked after the element is rendered.

Aliases: [afterRender]

Usage example:

<div afterRender="function (target, viewModel) {
    console.log('Rendered element:', target);
    console.log('Associated view model:' viewModel);
    console.log(this === viewModel);
}"></div>

autoselect

The autoselect binding automatically highlights the text in an input element, when it gets focus.

Source: <Magento_Ui_module_dir>/view/base/web/js/lib/knockout/bindings/autoselect.js. See on Github. Value type: Boolean

Defines whether the binding is enabled (true) or disabled (false).

Aliases: [autoselect]

Usage example:

<!-- as an attribute -->
<input type="text" autoselect/>

<!-- in a standard KO form -->
<input type="text" data-bind="autoselect: true"/>

bindHtml

The bindHtml binding renders the provided string, as a collection of HTML elements, inside of the associated node.

It also instantiates all bindings defined for the rendered elements in the scope of the current view model.

Source: <Magento_Ui_module_dir>/view/base/web/js/lib/knockout/bindings/bind-html.js. See on Github.

Value type: String

Aliases: [bindHtml]

Usage example:

<div bindHtml="
    <div data-bind='text: \'String from the text binding\''></div>
"></div>

collapsible

The collapsible binding provides methods and properties required for implementing collapsible panels. It can automatically collapse panel when clicking outside of the associated node, toggle optional CSS class when node changes its visibility. It has additional helper bindings: toggleCollapsible, openCollapsible and closeCollapsible.

Source: <Magento_Ui_module_dir>/view/base/web/js/lib/knockout/bindings/collapsible.js. See on Github.

Value type: Object

Binding’s configuration that may include the following properties:

Aliases: [collapsible]

datepicker

The datepicker binding is an adapter for the mage/calendar.js widget.

Source: <Magento_Ui_module_dir>/view/base/web/js/lib/knockout/bindings/datepicker.js. See on Github

Value type: String|Object

Aliases: -

Usage example:

<input type="text" data-bind="datepicker: value"/>

fadeVisible

The fadeVisible binding performs the gradual change of the element’s visibility (with an animation effect).

Source: <Magento_Ui_module_dir>/view/base/web/js/lib/knockout/bindings/fadeVisible.js. See on Github.

Value type: Boolean

Defines whether the element is visible (true) or hidden (false).

Aliases: -

Usage example:

<div data-bind="fadeVisible: isVisible">Foo Bar</div>
<button click="function () { isVisible(!isVisible()); }">Toggle</button>

i18n

The i18n binding is used to translate a string according to the currently enabled locale. Additionally, it creates the necessary elements for the TranslateInline jQuery widget, if it’s enabled on the page.

Source: <Magento_Ui_module_dir>/view/base/web/js/lib/knockout/bindings/i18n.js. See on Github.

Value type: string

Aliases: [translate], <translate>

Usage example:

<div data-bind="i18n: 'Translate as a standard knockout binding'"></div>

<div translate="'Translate using the attribute'"></div>

<translate args="'Translate using the tag'"></translate>

keyboard

The keyboard binding allows setting up listeners for the keypress event of a specific key.

Source: <Magento_Ui_module_dir>/view/base/web/js/lib/knockout/bindings/keyboard.js. See on Github.

Value type: [name: number]: (e: KeyboardEvent) => void

A collection in which keys represent keyboard keys codes and values are callback functions invoked when the associated key is pressed.

Aliases: [keyboard]

Usage example:

<input type="text" keyboard="{
    13: function (e) {
        console.log('Enter key has been pressed!');
    }
}"/>

mageInit

The mageInit binding is an adapter for the [data-mage-init] attribute that is used to initialize jQuery widgets on the associated element.

Source: <Magento_Ui_module_dir>/view/base/web/js/lib/knockout/bindings/mage-init.js. See on Github.

Value type: [path: string]: Object

Aliases: -

Usage example: creating modal window

<div mageInit="{
    'Magento_Ui/js/modal/modal': {
        autoOpen: true,
        buttons: false,
        modalClass: 'modal-system-messages',
        title: 'Hello world!'
    }
}"></div>

optgroup

The optgroup binding is a decorator for the standard Knockout’s options binding which adds the support of nested options, and renders them as the <optgroup> element.

Source: <Magento_Ui_module_dir>/view/base/web/js/lib/knockout/bindings/optgroup.js. See on Github.

Value type: Array<string> | Array<Object>

Aliases: -

Usage example:

<select data-bind="
    optionsValue: 'value',
    optionsText: 'label',
    optgroup: [{
        label: 'Swedish Cars',
        value: [{
            label: 'Volvo',
            value: 'volvo'
        }, {
            label: 'Saab',
            value: 'saab'      
        }]
    }, {
        label: 'German Cars',
        value: [{
            label: 'Mercedes',
            value: 'mercedes'
        }]
    }]"></select>

outerClick

The outerClick binding allows to subscribe for the “click” event that happens outside of the boundaries of the associated element.

Source: <Magento_Ui_module_dir>/view/base/web/js/lib/knockout/bindings/outer_click.js. See on Github.

Value type: Function.

Callback that is invoked when user clicks outside of the element.

Aliases: [outerClick]

Usage example:

<div id="target" outerClick="function () {
    console.log('Clicked outside of the "target" node.');
}">
</div>

range

The range binding is an adapter for the jQuery UI Slider widget. It also implements necessary handlers to work with mobile devices.

Source: <Magento_Ui_module_dir>/view/base/web/js/lib/knockout/bindings/range.js. See on Github.

Value type: Object.

Configuration that is passed to the Slider widget.

Aliases: [range]

Usage example:

<div
    class="data-slider"
    range="{
        value: scale,
        min: 1,
        max: 200,
        step: 1
}"></div>

resizable

The resizable binding is an adapter for the jQuery UI Resizable widget.

Source: <Magento_Ui_module_dir>/view/base/web/js/lib/knockout/bindings/resizable.js. See on Github.

Value type: Object.

Configuration for the Resizable widget.

Aliases: [resizable]

Usage example:

<div data-bind="resizable: {maxHeight: 200}"></div>

scope

A binding that allows evaluating descendant nodes in the scope of an object found in the UiRegistry by provided string.

Source: <Magento_Ui_module_dir>/view/base/web/js/lib/knockout/bindings/scope.js. See on Github.

Value type: String.

Component’s name by which to perform a lookup in the registry.

Aliases: [ko-scope], <scope>

Usage example:

<!-- as an attribute -->
<div ko-scope="'name.of.component'"></div>

<!-- in a standard KO form -->
<div data-bind="scope: 'name.of.component'"></div>

<!-- without an extra container node -->
<scope args="'name.of.component'"></scope>

staticChecked

The staticChecked binding implements the behavior similar to the standard checked binding. The difference is that staticChecked doesn’t change the array of the already selected elements if the value of the associated DOM element changes.

Source: <Magento_Ui_module_dir>/view/base/web/js/lib/knockout/bindings/staticChecked.js. See on Github.

Value type: Boolean | String | Number | Array<String|Number|Number>

Aliases: [staticChecked]

<input type="checkbox" data-bind="staticChecked: observable"/>

template

Magento template binding is a customization of the existing Knockout template binding. It is used to render a template inside of the associated element. The original Knockout’s implementation was overridden to support asynchronous loading of templates by the provided path, instead of searching for them on the page.

Source: <Magento_Ui_module_dir>/view/base/web/js/lib/knockout/template/engine.js. See on Github.

Value type: String | Object

Сonfiguration for the template binding. If the provided value is a string, it is processed as a path to .html file.

Aliases: [render], <render>

Usage example:

<div data-bind="template: 'path/to/the/template'"></div>

tooltip

Magento custom knockout binding for displaying a tooltip.

Source: <Magento_Ui_module_dir>/view/base/web/js/lib/knockout/bindings/tooltip.js. See on Github.

Value type: Object

Binding’s configuration that may include the following options:

Aliases: [tooltip]

Usage example:

Adding the tooltip binding as an attribute:

<div tooltip="
     trigger: '[data-tooltip-trigger=trigger]', 
     action: 'click', 
     delay: 300, 
     track: true,
     position: 'top' 
 "> Tooltip data </div>
 
<div data-tooltip-trigger="trigger"/>

Adding the tooltip binding as a node:

<div data-bind="
    tooltip: {
        trigger: '[data-tooltip-trigger=trigger]',
        action: 'click', 
        delay: 300, 
        track: true,
        position: 'top' 
    }  
"> Tooltip data </div>
 
<div data-tooltip-trigger="trigger"/>