ComboBox

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

<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>

  let games:ComboBox = new ComboBox();
  games.appendTo("#list");

Properties

actionFailureTemplate

string | Function

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

Defaults to ‘Request failed’

allowCustom

boolean

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

Defaults to true

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.

Defaults to false

allowObjectBinding

boolean

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

Defaults to false

allowResize

boolean

Gets or sets a value that indicates whether the DropDownList popup can be resized. When set to true, a resize handle appears in the bottom-right corner of the popup, allowing the user to resize the width and height of the popup.

Defaults to false

autofill

boolean

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

Defaults to false

cssClass

string

Sets CSS classes to the root element of the component that allows customization of appearance.

Defaults to null

dataSource

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

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.

Defaults to []

enablePersistence

boolean

Enable or disable persisting 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

enableVirtualization

boolean

Defines whether to enable virtual scrolling in the component.

Defaults to false

enabled

boolean

Specifies a value that indicates whether the 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: DropDownList = new DropDownList({
   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, disabled: null}

filterType

FilterType

Determines on which filter type, the 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 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

htmlAttributes

{ : }

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

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

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

let sportsData: { [key: string]: Object; }[] = [
  { Id: "Game1", Game: "American Football" },
  { Id: "Game2", Game: "Badminton" },
  { Id: "Game3", Game: "Basketball" },
  { Id: "Game4", Game: "Cricket" },
  { Id: "Game5", Game: "Football" }];
// initialize ComboBox component
let comboBoxObj: ComboBox = new ComboBox({
  //set the local data to dataSource property
  dataSource: sportsData,
  // map the appropriate columns to fields property
  fields: { text: 'Game', value: 'Id' },
  // set the placeholder to ComboBox input element
  placeholder: 'Select a game',
  value: "Basketball",
  htmlAttributes: { name: "games", readonly: "readonly", title: "ComboBox" }
});
comboBoxObj.appendTo('#games');

Defaults to {}

ignoreAccent

boolean

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

ignoreCase

boolean

When set to ‘false’, consider the case-sensitive on performing the search to find suggestions. By default consider the casing.

Defaults to true

index

number | null

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

Defaults to null

isDeviceFullScreen

boolean

Defines whether the popup opens in fullscreen mode on mobile devices when filtering is enabled. When set to false, the popup will display similarly on both mobile and desktop devices.

Defaults to true

itemTemplate

string | Function

Accepts the template design and assigns it to each list item present in the popup. 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’

noRecordsTemplate

string | Function

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

Defaults to ‘No records found’

placeholder

string

Specifies a short hint that describes the expected value of the DropDownList component.

Defaults to null

popupHeight

string | number

Specifies the height of the popup list.

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

Defaults to ‘300px’

popupWidth

string | number

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

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

Defaults to ‘100%’

query

Query

Accepts the external Query that execute along with data processing.

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

import { ComboBox } from '@syncfusion/ej2-dropdowns';
import { Query, DataManager, WebApiAdaptor } from '@syncfusion/ej2-data';

// initialize ComboBox component
let comboBoxObj: ComboBox = new ComboBox({
  //set the local data to dataSource property
  dataSource: new DataManager({
    url: 'https://ej2services.syncfusion.com/production/web-services/api/Employees',
    adaptor: new WebApiAdaptor,
    crossDomain: true
  }),
  // bind the Query instance to query property
  query: new Query().select(['FirstName', 'EmployeeID']).take(10).requiresCount(),
  // map the appropriate columns to fields property
  fields: { text: 'FirstName', value: 'EmployeeID' },
  // set the placeholder to ComboBox input element
  placeholder: 'Select a name',
});
comboBoxObj.appendTo('#games');

Defaults to null

readonly

boolean

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

Defaults to false

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.

Defaults to true

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

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

Defaults to null

value

number | string | boolean | object | null

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

Defaults to null

width

string | number

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.

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 combobox 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 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

disableItem

Method to disable specific item in the popup.

Returns void

filter

To filter the data from given data source by using query

Returns void

focusIn

Sets the focus to the component for interaction.

Returns void

focusOut

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

Returns void

getDataByValue

Gets the data Object that matches the given value.

Returns * { : }** | *string | number | boolean

getItems

Gets all the list items bound on this component.

Returns Element[]

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 it is in 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

showPopup

Opens the popup that displays the list of items.

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>

Triggers when the popup before opens.

blur

EmitType<Object>

Triggers when focus moves out from the component.

change

EmitType<ChangeEventArgs>

Triggers when an item in a popup is selected or when the model value is changed by user. Use change event to Configure the Cascading DropDownList

close

EmitType<PopupEventArgs>

Triggers when the popup is closed.

created

EmitType<Object>

Triggers when the component is created.

customValueSpecifier

EmitType<CustomValueSpecifierEventArgs>

Triggers on set a custom value to this component.

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 on typing a character in the component.

For more details about the filtering refer to Filtering documentation.

focus

EmitType<Object>

Triggers when the component is focused.

open

EmitType<PopupEventArgs>

Triggers when the popup opens.

resizeStart

EmitType<Object>

Triggers when the user starts resizing the DropDown popup.

resizeStop

EmitType<Object>

Triggers when the user finishes resizing the DropDown popup.

resizing

EmitType<Object>

Triggers continuously while the DropDown popup is being resized by the user. This event provides live updates on the width and height of the popup.

select

EmitType<SelectEventArgs>

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