Multiselect widget

This widget enables multiple select capability in the search field to help users choose different options.

The Multiselect widget source is the lib/web/mage/multiselect.js file.

Initialize

For information about how to initialize a widget in a JS component or .phtml template, see the Initialize JavaScript topic.

The following example shows how to instantiate the Multiselect widget:

Copy
$("#multiselect").multiselect2({});
Copied to your clipboard
$("#multiselect").multiselect2({});

where #multiselect is the selector of the select element for which Multiselect is initialized.

The following example shows a PHTML file using the script:

Copy
<script>
    require([
        'jquery',
        'mage/multiselect'
    ], function ($) {
        'use strict';

        $("#multiselect").multiselect2({});
    });
</script>
Copied to your clipboard
<script>
    require([
        'jquery',
        'mage/multiselect'
    ], function ($) {
        'use strict';

        $("#multiselect").multiselect2({});
    });
</script>

Options

containerClass

The class which is attached to the container with multi-select container selector.

Type: String

Default value: 'paginated'

currentPage

Current page of multi-select items.

Type: Integer

Default value: 1

lastAppendValue

The value of the last added multi-select item.

Type: Integer, String

Default value: 0

mselectCheckedClass

The class which is attached to a checked multi-select item.

Type: String

Default value: 'mselect-checked'

mselectContainer

Multiselect container selector.

Type: String

Default value: 'section.mselect-list'

mselectItemsWrapperClass

Multiselect items wrapper class.

Type: String

Default value: 'mselect-items-wrapper'

nextPageUrl

The URL of the controller or API which returns the JSON response.

Copy
{
  "success": true,
  "errorMessage": "",
  "result": [
    {
      "value": "1",
      "label": "Multi-select item label #1"
    },
    {
      "value": "2",
      "label": "Multi-select item label #2"
    }
  ]
}
Copied to your clipboard
{
  "success": true,
  "errorMessage": "",
  "result": [
    {
      "value": "1",
      "label": "Multi-select item label #1"
    },
    {
      "value": "2",
      "label": "Multi-select item label #2"
    }
  ]
}

An example of the controller: <Magento_Tax_module_dir>/Controller/Adminhtml/Rule/AjaxLoadRates.php

Type: String

Default value: undefined

searchInputClass

Class of the search input.

Type: String

Default value: 'admin__action-multiselect-search'

selectedItemsCountClass

Class of the selected items counter.

Type: String

Default value: 'admin__action-multiselect-search'

updateDelay

The search field update delay.

Type: Integer, String

Default value: 0

Methods

appendOptions

The method appends multi-select items to the multi-select.

Code example:

Copy
$('#multiselect').multiselect2('appendOptions', [{"value": "1", "label": "Label #1"}, {"value": "2", "label": "Label #2"}]);
Copied to your clipboard
$('#multiselect').multiselect2('appendOptions', [{"value": "1", "label": "Label #1"}, {"value": "2", "label": "Label #2"}]);

clearMultiselectOptions

The method removes all multi-select items.

Code example:

Copy
$('#multiselect').multiselect2('clearMultiselectOptions');
Copied to your clipboard
$('#multiselect').multiselect2('clearMultiselectOptions');

getCurrentPage

The method returns the number of the current page.

Copy
$('#multiselect').multiselect2('getCurrentPage');
Copied to your clipboard
$('#multiselect').multiselect2('getCurrentPage');

getSearchCriteria

The method returns the trimmed value of the search input.

Code example:

Copy
$('#multiselect').multiselect2('getSearchCriteria');
Copied to your clipboard
$('#multiselect').multiselect2('getSearchCriteria');

isOptionsLoaded

The method checks if all multi-select items are already loaded.

Copy
$('#multiselect').multiselect2('isOptionsLoaded', [{"value": "2", "label": "Label #2"}]);
Copied to your clipboard
$('#multiselect').multiselect2('isOptionsLoaded', [{"value": "2", "label": "Label #2"}]);

This method returns true if multiple selection items are loaded, and it returns false if they are not loaded.

loadOptions

The method loads the next page with multi-select items from nextPageUrl according to the search criteria. The multi-select items from the Ajax response are appended to the multi-select.

Code example:

Copy
$('#multiselect').multiselect2('loadOptions');
Copied to your clipboard
$('#multiselect').multiselect2('loadOptions');

setCurrentPage

The method configures the current page number.

Copy
$('#multiselect').multiselect2('setCurrentPage', 2);
Copied to your clipboard
$('#multiselect').multiselect2('setCurrentPage', 2);

Code sample

The following example shows the multiselect field with search bar and Add new value button.

Copy
<div class="select-example">
    <select id="multiselect" name="multiselect-field" multiple="multiple">
            <option value="1">Option 1</option>
            <option value="2">Option 2</option>
            <option value="3">Option 3</option>
            <option value="4">Option 4</option>
            <option value="5">Option 5</option>
            <option value="6">Option 6</option>
    </select>
    <script>
        require(['jquery', 'mage/multiselect'], function ($) {
            $('#multiselect').multiselect2({selectedValues: [2, 4]});
        });
    </script>
</div>
Copied to your clipboard
<div class="select-example">
    <select id="multiselect" name="multiselect-field" multiple="multiple">
            <option value="1">Option 1</option>
            <option value="2">Option 2</option>
            <option value="3">Option 3</option>
            <option value="4">Option 4</option>
            <option value="5">Option 5</option>
            <option value="6">Option 6</option>
    </select>
    <script>
        require(['jquery', 'mage/multiselect'], function ($) {
            $('#multiselect').multiselect2({selectedValues: [2, 4]});
        });
    </script>
</div>

Result

As a result, we see the multiselect field with search bar and Add new value button. You can now search for an option in the search bar and the Add new value button allows you to add a new option to the multiselect feature.

Last updated 9/11/2023

Was this helpful?

Yes

No