ejComboBox

11 Jul 201815 minutes to read

The ComboBox component allows the user to type a value or choose an option from the list of predefined options.

Syntax

JAVASCRIPT

$(element).ejComboBox()

Example

HTML

<input type="text" id="combobox" /> 
	<script> 
	// Create ComboBox 
	$('#ComboBox').ejComboBox({ 
		dataSource: window.carList,
		value:"Austin-Healey" 
	}); 
	</script>

Requires

• module:jQuery

• module:ej.core.js

• module:ej.data.js

• module:ej.globalize.js

• module:ej.combobox.js

Members

actionFailureTemplate string

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

Default Value:

• “The Request Failed”

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
		dataSource: window.carList,  
		actionFailureTemplate:"Data Not Load" 
	});

allowCustom boolean

Specifies whether the component allows user defined value which does not exist in data source.

Default Value:

• true

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
		allowCustom: false 
	});

allowFiltering boolean

When allowFiltering is set to true, show the filter bar (search box) of the component. The filter action retrieves matched items through the filtering event based on the characters typed in the search TextBox. If no match is found, the value of the noRecordsTemplate property will be displayed.

Default Value:

• false

Example

HTML

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

JAVASCRIPT

var searchData = [ {id: 's1', country: 'California'}, {id: 's2', country: 'India'},
{id: 's3', country: 'USA'}, {id: 's4', country: 'England'}]
  $("#list").ejComboBox({ 
     dataSource: searchData,
     fields: { text: "country", value: "id" },
     allowFiltering: true,
     filtering: function (e) {
         let query = new Query();
         query = (e.text != "") ? query.where("country", "startswith", e.text, true) : query;
         e.updateData(searchData, query);
     }
  });

autofill boolean

Specifies whether suggest a first matched item in input when searching. No action happens when no matches found.

Default Value:

• false

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
		autofill: true
	});

cssClass string

Sets CSS classes to the root element of the component that helps customize the UI styles.

Default Value:

• null

Example

JAVASCRIPT

<style type="text/css">
   .gradient-green {
       font-family: cursive;
   }
</style>
</script>
	$("#combobox").ejComboBox({ 
		cssClass: 'gradient-lime' 
	});
</script>

dataSource Object|Array

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

Default Value:

• []

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
		dataSource: window.carList, 
		value: "Austin-Healey" 
	});

enableRtl boolean

When set to true, enables RTL mode of the component that displays the content in the right-to-left direction.

Default Value:

• false

Example

JAVASCRIPT

$("#combobox").ejComboBox({
		enableRtl: true 
	});

enabled boolean

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

Default Value:

• true

Example

JAVASCRIPT

$("#combobox").ejComboBox({
		enabled: false 
	});

fields Object

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

fields.groupBy string

Used to group the popup list items.

Default Value:

• null

fields.iconCss string

Defines class for the item.

Default Value:

• null

fields.value string

Defines the specific field name which contains unique values for the list items.

Default Value:

• null

fields.text string

Defines the specific field name in the data source to load the popup list with data.

Default Value:

• null

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
		fields: { 
			text: "name", 
			value: "id" 
		} 
	});

footerTemplate string

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

Default Value:

• null

Example

JAVASCRIPT

$("#combobox").ejComboBox({
		footerTemplate: '<div class="Foot"> Total Items Count: 5 </div>'
	});

groupTemplate string

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

Default Value:

• null

Example

JAVASCRIPT

$("#combobox").ejComboBox({
		groupTemplate: '<div class="group"> Contact Info </div>'
	});

headerTemplate string

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

Default Value:

• null

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
		headerTemplate: '<div class="head">  Photo  <span style="padding-left:42px"> Contact Info </span></div>'
	});

htmlAttributes object

Allows additional HTML attributes such as title, name, etc., and accepts n number of attributes in a key-value pair format.

Default Value:

• {}

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
		htmlAttributes: { title: 'List of games available here.' }
	});

index number

Gets or sets the index of the selected item in the component.

Default Value:

• null

Example

JAVASCRIPT

$("#combobox").ejComboBox({index: 1});

itemTemplate string

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

Default Value:

• null

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
		itemTemplate: '<div><img class="eimg" src="${eimg}.png" alt="employee"/>' +
                    '<div class="ename"> ${text} </div><div class="temp"> ${country} </div></div>'
	});

locale string

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

Default Value:

• “en-US”

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
		locale: "es-ES"
	});

noRecordsTemplate string

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

Default Value:

• No Records Found

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
		noRecordsTemplate:"Data Not Found"
	});

placeholder string

Accepts the value to be displayed as a watermark text on the component input.

Default Value:

• null

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
		placeholder:"Select text"
	});

popupHeight string|number

Specifies the height of the popup list.

Default Value:

• “300px”

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
		popupHeight: "400px"
	});

popupWidth string|number

Specifies the width of the popup list. By default, the popup width sets based on the width of the component.

Default Value:

• “100%”

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
		popupWidth: "300px"
	});

query ej.Query

The query to retrieve the data from the data source.

Default Value:

• null

Example

JAVASCRIPT

var dataManger = ej.DataManager({ 
		url: "http://mvc.syncfusion.com/Services/Northwnd.svc/" 
	});
	
	var query = ej.Query().from("Suppliers").select("ContactName");
	
	$("#combobox").ejComboBox({ 
		dataSource: dataManger, 
		query: query, 
		fields: { 
			text: "ContactName" 
		}
	});

readonly boolean

When set to true, the user interactions on the component are disabled.

Default Value:

• false

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
    	readonly: true
	});

showClearButton boolean

Specifies whether to show or hide the clear button. When the clear button is clicked, value, text, and index properties are reset to null.

Default Value:

• true

Example

HTML

$("#combobox").ejComboBox({ 
	 	showClearButton:true
	});

sortOrder enum

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

Name	Description
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.

Default Value:

• ej.SortOrder.None

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
		sortOrder: ej.SortOrder.Decending 
	});

text string

Gets or sets the display text of the selected item in the component.

Default Value:

• null

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
		dataSource: window.carList, 
		text: "Austin-Healey"
	});

value number|string

Gets or sets the value of the selected item in the component.

Default Value:

• null

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
		dataSource: window.carList, 
		value: "Austin-Healey"
	});

width number|string

Specifies the width of the component. By default, the component width sets based on the width of its parent container. You can also set the width in pixel values.

Default Value:

• “100%”

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
		width: "300px"
	});

Methods

addItem()

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

Name	Type	Description
items	[] | Object	Specifies an array of JSON data or a JSON data.
itemIndex (optional)	number	Specifies the index to place the newly added item in the popup list.

Returns: void

Example

JAVASCRIPT

$("#combobox").ejComboBox("addItem",{ id: 'level11', sports: 'cricket' });

focusIn()

Sets the focus to the component for interaction.

Returns: void

Example

JAVASCRIPT

$("#combobox").ejComboBox("focusIn");

focusOut()

Moves the focus from the component if the component is already focused.

Returns: void

Example

JAVASCRIPT

$("#combobox").ejComboBox("focusOut");

getDataByValue()

Gets the data object that matches the given value.

Name	Type	Description
value	string | number	Specifies the value of the list item.

Returns: object

Example

JAVASCRIPT

$("#combobox").ejComboBox("getDataByValue","value");

getItems()

Gets all the list items bound on this component.

Returns: Element[]

Example

JAVASCRIPT

$("#combobox").ejComboBox("getItems");

hidePopup()

Hides the popup if it is in open state.

Returns: void

Example

JAVASCRIPT

$("#combobox").ejComboBox("hidePopup");

showPopup()

Opens the popup that displays the list of items.

Returns: void

Example

JAVASCRIPT

$("#combobox").ejComboBox("showPopup");

Events

actionBegin

Triggers before fetching data from the remote server.

Name	Type	Description
cancel	boolean	if the event should be canceled; otherwise, false.
model	object	returns the ComboBox model
type	string	returns the name of the event

NOTE

It internally uses jQuery ajaxStart event. For details refer here.

Example

JAVASCRIPT

$("#combobox").ejComboBox({
		actionBegin:function(arg){
			//Action Success Code
		} 
	});

actionComplete

Triggers after data is fetched successfully from the remote server.

Name	Type	Description
cancel	boolean	if the event should be canceled; otherwise, false.
model	object	returns the Autocomplete model
e	object	Returns the query for data retrieval from the Database
type	string	returns the name of the event

NOTE

It internally uses jQuery ajaxComplete event. For details refer here.

Example

JAVASCRIPT

$("#combobox").ejComboBox({
		actionComplete:function(arg){
			//Action Complete Code
		} 
	});

actionFailure

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

Name	Type	Description
cancel	boolean	if the event should be canceled; otherwise, false.
e	object	Returns the error message
model	object	returns the Autocomplete model
type	string	returns the name of the event

NOTE

It internally uses jQuery ajaxError event. For details refer here.

Example

JAVASCRIPT

$("#combobox").ejComboBox({
		actionFailure:function(arg){
			//Action Failure Code
		} 
	});

change

Triggers when an item in a popup is selected or when the model value is changed.

</tr>

Name	Type	Description
cancel	boolean	Set this option to true to cancel the event.
model	Object	Instance of the combobox model object.
type	string	Name of the event.
value	string|number	Value of the combobox textbox.
itemData	Object	Data object of the selected item.
Item	Object	Li element of the selected item.
e	Object	Event argument.
isInteracted	boolean	value of the interaction

Example

JAVASCRIPT

$("#combobox").ejComboBox({
		change: function (argument) {
			//do something
		}
	});

close

Triggers when the popup is closed.

Name	Type	Description
popup	object	Element of the combobox popup list

Example

JAVASCRIPT

$("#combobox").ejComboBox({ 
		close: function (argument) {
			//do something
		}
	});

create

Triggers when ComboBox widget is created.

Name	Type	Description
cancel	boolean	Set this option to true to cancel the event.
model	Object	Instance of the combobox model object.
type	string	Name of the event.

Example

JAVASCRIPT

$("#combobox").ejComboBox({
		create: function (argument) {
			//do something
		}
	});

customValueSpecifier

Triggers on set a custom value to this component.

Name	Type	Description
model	Object	Instance of the combobox model object.
type	string	Name of the event.
text	string	text of the combobox.

Example

JAVASCRIPT

$("#combobox").ejComboBox({
		customValueSpecifier: function (argument) {
			//do something
		}
	});

filtering

Triggers on typing a character in the component.

Name	Type	Description
model	Object	Instance of the combobox model object.
type	string	Name of the event.
text	string	text of the combobox.
updateData	function	Function used to update the filtering value.

Example

JAVASCRIPT

$("#combobox").ejComboBox({
		filtering: function (argument) {
			//do something
		}
	});

focus

Triggers when the component is focused.

Name	Type	Description
cancel	boolean	Set this option to true to cancel the event.
model	Object	Instance of the combobox model object.
type	string	Name of the event.

Example

JAVASCRIPT

$("#combobox").ejComboBox({
		focus: function () {
			//do something
		}
	});

open

Triggers after the suggestion list is opened.

Name	Type	Description
popup	object	Element of the combobox popup list

Example

JAVASCRIPT

$("#combobox").ejComboBox({  
		open: function (argument) {
			//do something
		}
	});

select

Triggers when an item in the popup is selected.

Name	Type	Description
cancel	boolean	Set this option to true to cancel the event.
model	Object	Instance of the combobox model object.
type	string	Name of the event.
value	string|number	Value of the combobox textbox.
text	string	Text of the selected item.
itemData	Object	Data object of the selected item.
Item	Object	Li element of the selected item.
e	Object	Event argument.
isInteracted	boolean	value of the interaction

Example

JAVASCRIPT

$("#combobox").ejComboBox({
		select: function (argument) {
			//do something
		}
	});