ListBox

23 Sep 202516 minutes to read

The ListBox is a graphical user interface component used to display a list of items.
Users can select one or more items in the list using a checkbox or by keyboard selection.
It supports sorting, grouping, reordering and drag and drop of items.

<select id="listbox">
     <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 listObj = new ListBox();
  listObj.appendTo("#listbox");
</script>

Properties

allowDragAndDrop boolean

If ‘allowDragAndDrop’ is set to true, then you can perform drag and drop of the list item.
ListBox contains same ‘scope’ property enables drag and drop between multiple ListBox.

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 false

cssClass string

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

Defaults to ’’

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.

value

Defaults to false

enableRtl boolean

Enable or disable rendering component in right to left direction.

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}

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 component needs to be considered on search action.
The FilterType and its supported data types are

FilterType	Description	Supported Types
StartsWith	Checks whether a value begins with the specified value.	String
EndsWith	Checks whether a value ends with specified value.	String
Contains	Checks whether a value contains with specified value.	String

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

Defaults to ‘StartsWith’

height number|string

Sets the height of the ListBox component.

Defaults to ’’

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’

maximumSelectionLength number

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

Defaults to 1000

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’

query Query

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

Defaults to null

scope string

Defines the scope value to group sets of draggable and droppable ListBox.
A draggable with the same scope value will be accepted by the droppable.

Defaults to ’’

selectionSettings SelectionSettingsModel

Specifies the selection mode and its type.

Defaults to { mode: ‘Multiple’, type: ‘Default’ }

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

toolbarSettings ToolbarSettingsModel

Specifies the toolbar items and its position.

Defaults to { items: [], position: ‘Right’ }

value string[]|number[]|boolean[]

Sets the specified item to the selected state or gets the selected item in the ListBox.

Defaults to []

Methods

addEventListener

Adds the handler to the given event listener.

Parameter	Type	Description
eventName	`string`	A String that specifies the name of the event
handler	`Function`	Specifies the call to run when the event occurs.

Returns void

addItems

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

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

Returns void

appendTo

Appends the control within the given HTML element

Parameter	Type	Description
selector (optional)	`string` \| `HTMLElement`	Target element where control needs to be appended

Returns void

attachUnloadEvent

Adding unload event to persist data when enable persistence true

Returns void

dataBind

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

Returns void

detachUnloadEvent

Removing unload event to persist data when enable persistence true

Returns void

enableItems

This method is used to enable or disable the items in the ListBox based on the items and enable argument.

Parameter	Type	Description
items	`string[]`	Text items that needs to be enabled/disabled.
enable	`boolean`	Set `true`/`false` to enable/disable the list items.
isValue (optional)	`boolean`	Set `true` if `items` parameter is a array of unique values.

Returns void

filter

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

| Parameter | Type | Description |
|——|——|————-|
| dataSource | ` { : }[] | DataManager | string[] | number[] | boolean[]| Set the data source to filter. | | query (*optional*) |Query| Specify the query to filter the data. | | fields (*optional*) | [FieldSettingsModel`](./fieldSettingsModel) | Specify the fields to map the column in the data table. |

Returns void

getDataByValue

Gets the data Object that matches the given value.

Parameter	Type	Description
value	`string` \| `number` \| `boolean` \| `object`	Specifies the value of the list item.

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

getDataByValues

Gets the array of data Object that matches the given array of values.

Parameter	Type	Description
value	`string[]` \| `number[]` \| `boolean[]`	Specifies the array value of the list item.

Returns * { : }[]*

getDataList

Gets the updated dataSource in ListBox.

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

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

getSortedList

Returns the sorted Data in ListBox.

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

handleUnload

Handling unload event to persist data when enable persistence true

Returns void

moveAllTo

Moves all the values from one ListBox to the scoped ListBox.

Parameter	Type	Description
targetId (optional)	`string`	Specifies the scoped ListBox ID.
index (optional)	`number`	Specifies the index to where the items moved.

Returns void

moveBottom

Moves the given value(s) / selected value(s) in bottom of the list.

Parameter	Type	Description
value (optional)	`string[]` \| `number[]` \| `boolean[]`	Specifies the value(s).

Returns void

moveDown

Moves the given value(s) / selected value(s) downwards.

Parameter	Type	Description
value (optional)	`string[]` \| `number[]` \| `boolean[]`	Specifies the value(s).

Returns void

moveTo

Moves the given value(s) / selected value(s) to the given / default scoped ListBox.

Parameter	Type	Description
value (optional)	`string[]` \| `number[]` \| `boolean[]`	Specifies the value or array value of the list item.
index (optional)	`number`	Specifies the index.
targetId (optional)	`string`	Specifies the target id.

Returns void

moveTop

Moves the given value(s) / selected value(s) in Top of the list.

Parameter	Type	Description
value (optional)	`string[]` \| `number[]` \| `boolean[]`	Specifies the value(s).

Returns void

moveUp

Moves the given value(s) / selected value(s) upwards.

Parameter	Type	Description
value (optional)	`string[]` \| `number[]` \| `boolean[]`	Specifies the value(s).

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.

Parameter	Type	Description
eventName	`string`	A String that specifies the name of the event to remove
handler	`Function`	Specifies the function to remove

Returns void

removeItem

Removes a item from the list. By default, removed the last item in the list,
but you can remove based on the index parameter.

Parameter	Type	Description
items (optional)	` `{ : }`[] `\|` `{ : }` `\|` string `\|` boolean `\|` number `\|` string[] `\|` boolean[] `\|` number[]`	Specifies an array of JSON data or a JSON data.
itemIndex (optional)	`number`	Specifies the index to remove the item from the list.

Returns void

removeItems

Removes a item from the list. By default, removed the last item in the list,
but you can remove based on the index parameter.

Parameter	Type	Description
items (optional)	`obj[]` \| `obj`	Specifies an array of JSON data or a JSON data.
itemIndex (optional)	`number`	Specifies the index to remove the item from the list.

Returns void

selectAll

Based on the state parameter, entire list item will be selected/deselected.

Parameter	Type	Description
state	`boolean`	Set `true`/`false` to select/un select the entire list items.

Returns void

selectItems

Based on the state parameter, specified list item will be selected/deselected.

Parameter	Type	Description
items	`string[]`	Array of text value of the item.
state	`boolean`	Set `true`/`false` to select/un select the list items.
isValue (optional)	`boolean`	Set `true` if `items` parameter is a array of unique values.