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 the Multiselect widget
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:
1
$("#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:
1
2
3
4
5
6
7
8
9
10
<script>
require([
'jquery',
'mage/multiselect'
], function ($) {
'use strict';
$("#multiselect").multiselect2({});
});
</script>
Options
The Multiselect widget has the following options:
- containerClass
- currentPage
- lastAppendValue
- mselectCheckedClass
- mselectContainer
- mselectItemsWrapperClass
- nextPageUrl
- searchInputClass
- selectedItemsCountClass
- updateDelay
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"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
The Multiselect methods are the following:
- appendOptions()
- clearMultiselectOptions()
- getCurrentPage()
- getSearchCriteria()
- isOptionsLoaded()
- loadOptions()
- setCurrentPage()
appendOptions
The method appends multi-select items to the multi-select.
Code example:
1
$('#multiselect').multiselect2('appendOptions', [{"value": "1", "label": "Label #1"}, {"value": "2", "label": "Label #2"}]);
clearMultiselectOptions
The method removes all multi-select items.
Code example:
1
$('#multiselect').multiselect2('clearMultiselectOptions');
getCurrentPage
The method returns the number of the current page.
1
$('#multiselect').multiselect2('getCurrentPage');
getSearchCriteria
The method returns the trimmed value of the search input.
Code example:
1
$('#multiselect').multiselect2('getSearchCriteria');
isOptionsLoaded
The method checks if all multi-select items are already loaded.
1
$('#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:
1
$('#multiselect').multiselect2('loadOptions');
setCurrentPage
The method configures the current page number.
1
$('#multiselect').multiselect2('setCurrentPage', 2);
Code sample
The following example shows the multiselect field with search bar and Add new value button.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<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.