MultiSelect

The Multiselect allows the user to pick a more than one value from list of predefined values.

<select id="list">
     <option value='1'>Badminton</option>
     <option value='2'>Basketball</option>
     <option value='3'>Cricket</option>
     <option value='4'>Football</option>
     <option value='5'>Tennis</option>
</select>

<script>
  var multiselectObj = new Multiselect();
  multiselectObj.appendTo("#list");
</script>

Properties

actionFailureTemplate

string | Function

Accepts the template and assigns it to the popup list content of the MultiSelect component when the data fetch request from the remote server fails.

Defaults to ‘Request failed’

addTagOnBlur

boolean

By default, the typed value is converting into chip or update as value of the component when you press the enter key or select from the popup. If you want to convert the typed value into chip or update as value of the component while focusing out the component, then enable this property. If custom value is enabled, both custom value and value present in the list are converted into tag while focusing out the component; Otherwise, value present in the list is converted into tag while focusing out the component.

Defaults to false

allowCustomValue

boolean

Allows user to add a custom value, the value which is not present in the suggestion list.

Defaults to false

allowFiltering

boolean

To enable the filtering option in this component. Filter action performs when type in search box and collect the matched item through filtering event. If searching character does not match, noRecordsTemplate property value will be shown.

Defaults to null

allowObjectBinding

boolean

Defines whether the object binding is allowed or not in the component.

Defaults to false

changeOnBlur

boolean

By default, the multiselect component fires the change event while focus out the component. If you want to fires the change event on every value selection and remove, then disable the changeOnBlur property.

Defaults to true

closePopupOnSelect

boolean

Based on the property, when item get select popup visibility state will changed.

Defaults to true

cssClass

string

Sets the CSS classes to root element of this component which helps to customize the complete styles.

Defaults to null

dataSource

{ [key: string]: Object }[] | DataManager | string[] | number[] | boolean[]

Accepts the list items either through local or remote service and binds it to the MultiSelect component. It can be an array of JSON Objects or an instance of DataManager.

Defaults to []

delimiterChar

string

Sets the delimiter character for ‘default’ and ‘delimiter’ visibility modes.

Defaults to ’,’

enableGroupCheckBox

boolean

Specifies a Boolean value that indicates the whether the grouped list items are allowed to check by checking the group header in checkbox mode. By default, there is no checkbox provided for group headers. This property allows you to render checkbox for group headers and to select all the grouped items at once

Defaults to false

enableHtmlSanitizer

boolean

Defines whether to allow the cross-scripting site or not.

Defaults to true

enablePersistence

boolean

Enable or disable persisting MultiSelect component’s state between page reloads. If enabled, following list of states will be persisted.

1. value

Defaults to false

enableRtl

boolean

Enable or disable rendering component in right to left direction.

Defaults to false

enableSelectionOrder

boolean

Reorder the selected items in popup visibility state.

Defaults to true

enableVirtualization

boolean

Defines whether to enable virtual scrolling in the component.

Defaults to false

enabled

boolean

Specifies a value that indicates whether the MultiSelect component is enabled or not.

Defaults to true

fields

FieldSettingsModel

The fields property maps the columns of the data table and binds the data to the component.

• text - Maps the text column from data table for each list item.
• value - Maps the value column from data table for each list item.
• iconCss - Maps the icon class column from data table for each list item.

• groupBy - Group the list items with it’s related items by mapping groupBy field.

  <input type="text" tabindex="1" id="list"> </input>

  let customers: MultiSelect = new MultiSelect({
   dataSource:new DataManager({ url:'http://js.syncfusion.com/demos/ejServices/Wcf/Northwind.svc/' }),
   query: new Query().from('Customers').select(['ContactName', 'CustomerID']).take(5),
   fields: { text: 'ContactName', value: 'CustomerID' },
   placeholder: 'Select a customer'
  });
  customers.appendTo("#list");

Defaults to {text: null, value: null, iconCss: null, groupBy: null}

filterBarPlaceholder

string

Accepts the value to be displayed as a watermark text on the filter bar.

Defaults to null

filterType

FilterType

Determines on which filter type, the MultiSelect component needs to be considered on search action. The FilterType and its supported data types are

The default value set to StartsWith, all the suggestion items which contain typed characters to listed in the suggestion popup.

Defaults to ‘StartsWith’

floatLabelType

FloatLabelType

Specifies whether to display the floating label above the input element. Possible values are:

• Never: The label will never float in the input when the placeholder is available.
• Always: The floating label will always float above the input.
• Auto: The floating label will float above the input after focusing or entering a value in the input.

Defaults to Syncfusion.EJ2.Inputs.FloatLabelType.Never

footerTemplate

string | Function

Accepts the template design and assigns it to the footer container of the popup list.

For more details about the available template options refer to Template documentation.

Defaults to null

groupTemplate

string | Function

Accepts the template design and assigns it to the group headers present in the MultiSelect popup list.

Defaults to null

headerTemplate

string | Function

Accepts the template design and assigns it to the header container of the popup list.

For more details about the available template options refer to Template documentation.

Defaults to null

hideSelectedItem

boolean

Hides the selected item from the list item.

Defaults to true

htmlAttributes

{ [key: string]: string }

Gets or sets the additional attribute to HtmlAttributes property in MultiSelect, which helps to add attribute like title, name etc, input should be key value pair.

 <input type="text" id="country">

import { MultiSelect } from '@syncfusion/ej2-dropdowns';

let countries: { [key: string]: Object; }[] = [
  { Name: "Australia", Code: "AU" },
  { Name: "Bermuda", Code: "BM" },
  { Name: "Canada", Code: "CA" },
  { Name: "Cameroon", Code: "CM" },
  { Name: "Denmark", Code: "DK" }
];
// initialize MultiSelect component
let multiselect: MultiSelect = new MultiSelect({
  //set the local data to dataSource property
  dataSource: countries,
  // map the appropriate columns to fields property
  fields: { text: 'Name', value: 'Code' },
  htmlAttributes: { name: "country", placeholder: "Select a country", title: "MultiSelect DropDown" }
});
multiselect.appendTo('#country');

Defaults to {}

ignoreAccent

boolean

ignoreAccent set to true, then ignores the diacritic characters or accents when filtering.

ignoreCase

boolean

Sets case sensitive option for filter operation.

Defaults to true

itemTemplate

string | Function

Accepts the template design and assigns it to each list item present in the popup.

For more details about the available template options refer to Template documentation. We have built-in template engine which provides options to compile template string into a executable function. For EX: We have expression evolution as like ES6 expression string literals.

Defaults to null

locale

string

Overrides the global culture and localization value for this component. Default global culture is ‘en-US’.

Defaults to ‘en-US’

maximumSelectionLength

number

Sets limitation to the value selection. based on the limitation, list selection will be prevented.

Defaults to 1000

mode

visualMode

configures visibility mode for component interaction.

• Box - selected items will be visualized in chip.
• Delimiter - selected items will be visualized in text content.
• Default - on focus in component will act in box mode. on blur component will act in delimiter mode.
• CheckBox - The ‘checkbox’ will be visualized in list item.

Defaults to Default

noRecordsTemplate

string | Function

Accepts the template design and assigns it to popup list of MultiSelect component when no data is available on the component.

Defaults to ‘No records found’

openOnClick

boolean

Whether to automatically open the popup when the control is clicked.

Defaults to true

placeholder

string

Gets or sets the placeholder in the component to display the given information in input when no item selected.

Defaults to null

popupHeight

string | number

Gets or sets the height of the popup list. By default it renders based on its list item.

For more details about the popup configuration refer to Popup Configuration documentation.

Defaults to ‘300px’

popupWidth

string | number

Gets or sets the width of the popup list and percentage values has calculated based on input width.

For more details about the popup configuration refer to Popup Configuration documentation.

Defaults to ‘100%’

query

Query

Accepts the external Query which will execute along with the data processing in MultiSelect.

Defaults to null

readonly

boolean

Gets or sets the readonly to input or not. Once enabled, just you can copy or highlight the text however tab key action will perform.

Defaults to false

selectAllText

string

Specifies the selectAllText to be displayed on the component.

Defaults to ‘select All’

showClearButton

boolean

Enables close icon with the each selected item.

Defaults to true

showDropDownIcon

boolean

Allows you to either show or hide the DropDown button on the component

Defaults to false

showSelectAll

boolean

Allows you to either show or hide the selectAll option on the component.

Defaults to false

sortOrder

SortOrder

Specifies the sortOrder to sort the data source. The available type of sort orders are

• None - The data source is not sorting.
• Ascending - The data source is sorting with ascending order.
• Descending - The data source is sorting with descending order.

Defaults to null

text

string | null

Selects the list item which maps the data text field in the component.

Defaults to null

unSelectAllText

string

Specifies the UnSelectAllText to be displayed on the component.

Defaults to ‘select All’

value

number[] | string[] | boolean[] | any[] | null

Selects the list item which maps the data value field in the component.

 <input type="text" id="country">

import { MultiSelect } from '@syncfusion/ej2-dropdowns';

let countries: { [key: string]: Object; }[] = [
  { Name: "Australia", Code: "AU" },
  { Name: "Bermuda", Code: "BM" },
  { Name: "Canada", Code: "CA" },
  { Name: "Cameroon", Code: "CM" },
  { Name: "Denmark", Code: "DK" }
];
// initialize MultiSelect component
let multiselect: MultiSelect = new MultiSelect({
  //set the local data to dataSource property
  dataSource: countries,
  // map the appropriate columns to fields property
  fields: { text: 'Name', value: 'Code' },
  // set the placeholder to MultiSelect input element
  placeholder: 'Select a Country',
  value: ["CM"]
});
multiselect.appendTo('#country');

Defaults to null

valueTemplate

string | Function

Accepts the template design and assigns it to the selected list item in the input element of the component. For more details about the available template options refer to Template documentation. We have built-in template engine which provides options to compile template string into a executable function. For EX: We have expression evolution as like ES6 expression string literals.

Defaults to null

width

string | number

Gets or sets the width of the component. By default, it sizes based on its parent. container dimension.

Defaults to ‘100%’

zIndex

number

specifies the z-index value of the component popup element.

Defaults to 1000

Methods

addEventListener

Adds the handler to the given event listener.

Returns void

addItem

Adds a new item to the multiselect popup list. By default, new item appends to the list as the last item, but you can insert based on the index parameter.

Returns void

appendTo

Appends the control within the given HTML element

Returns void

attachUnloadEvent

Adding unload event to persist data when enable persistence true

Returns void

clear

Allows you to clear the selected values from the Multiselect component.

Returns void

dataBind

When invoked, applies the pending property changes immediately to the component.

Returns void

destroy

Removes the component from the DOM and detaches all its related event handlers. Also it removes the attributes and classes.

Returns void

detachUnloadEvent

Removing unload event to persist data when enable persistence true

Returns void

filter

To filter the multiselect data from given data source by using query

Returns void

focusIn

Sets the focus to widget for interaction.

Returns void

focusOut

Remove the focus from widget, if the widget is in focus state.

Returns void

getDataByValue

Gets the data Object that matches the given value.

Returns { [key: string]: Object } | string | number | boolean

getLocalData

Returns the persistence data for component

Returns any

getRootElement

Returns the route element of the component

Returns HTMLElement

handleUnload

Handling unload event to persist data when enable persistence true

Returns void

hidePopup

Hides the popup, if the popup in a open state.

Returns void

hideSpinner

Hides the spinner loader.

Returns void

refresh

Applies all the pending property changes and render the component again.

Returns void

removeEventListener

Removes the handler from the given event listener.

Returns void

selectAll

Based on the state parameter, entire list item will be selected/deselected. parameter true - Selects entire list items. false - Un Selects entire list items.

Returns void

showPopup

Shows the popup, if the popup in a closed state.

Returns void

showSpinner

Shows the spinner loader.

Returns void

Inject

Dynamically injects the required modules to the component.

Returns void

Events

actionBegin

EmitType<Object>

Triggers before fetching data from the remote server.

actionComplete

EmitType<Object>

Triggers after data is fetched successfully from the remote server.

actionFailure

EmitType<Object>

Triggers when the data fetch request from the remote server fails.

beforeOpen

EmitType<Object>

Fires when popup opens before animation.

beforeSelectAll

EmitType<ISelectAllEventArgs>

Fires before select all process.

blur

EmitType<Object>

Event triggers when the input get focus-out.

change

EmitType<MultiSelectChangeEventArgs>

Fires each time when selection changes happened in list items after model and input value get affected.

chipSelection

EmitType<Object>

Event triggers when the chip selection.

close

EmitType<PopupEventArgs>

Fires when popup close after animation completion.

created

EmitType<Object>

Triggers when the component is created.

customValueSelection

EmitType<CustomValueEventArgs>

Triggers when the customValue is selected.

dataBound

EmitType<Object>

Triggers when data source is populated in the popup list..

destroyed

EmitType<Object>

Triggers when the component is destroyed.

filtering

EmitType<FilteringEventArgs>

Triggers event,when user types a text in search box.

For more details about filtering, refer to Filtering documentation.

focus

EmitType<Object>

Event triggers when the input get focused.

open

EmitType<PopupEventArgs>

Fires when popup opens after animation completion.

removed

EmitType<RemoveEventArgs>

Fires after the selected item removed from the widget.

removing

EmitType<RemoveEventArgs>

Fires before the selected item removed from the widget.

select

EmitType<SelectEventArgs>

Triggers when an item in the popup is selected by the user either with mouse/tap or with keyboard navigation.

selectedAll

EmitType<ISelectAllEventArgs>

Fires after select all process completion.

tagging

EmitType<TaggingEventArgs>

Fires before set the selected item as chip in the component.

For more details about chip customization refer Chip Customization