Skip to main content

Configuration

Arrow keys navigation​

The List component lets you navigate its items with arrow keys. You can enable this functionality using the keyNavigation property:

const list = new dhx.List("list_container", {keyNavigation:true});

As a value of this option you can use either true/false to switch it on/off, or specify a function that defines custom navigation logic.

Default shortcut keys​

ArrowUpmoves focus to the previous item
ArrowDownmoves focus to the next item
Enter/Shift+Enter/Ctrl+Enteradds selection to a List item in focus
Enteradds selection to a List item in focus, activates editor for the selected item (when the "editable" property is enabled)
Ctrl+Aselects all items at once (when the "multiselection" property is enabled)

Drag-n-drop of items​

DHTMLX List supports drag-n-drop of items between lists in several modes. To begin with, specify the dragMode property in the configuration object of List. Then define which mode you need:

  • target - a list takes items from other lists, while its items can't be dragged out of it
  • source - a list allows dragging its items out and can't take items from other lists
  • both - a list both takes items from other lists and allows dragging its items out
const list = new dhx.List("list_container", { 
dragMode:"source"
});

To drag several items between lists, enable the multiselection in addition to the dragMode:

const list = new dhx.List("list_container", { 
dragMode:"source",
multiselection:true
});

Read more about multiselection in List below.

Related sample: List. Drag-n-drop

Dynamic rendering of items​

List loads and renders all data at once. If you use large amounts of data in the list, it may slow down your app.

You can increase the speed of an application that contains a List by enabling dynamic data rendering. This means that List renders data in parts and on demand. To make use of dynamic data rendering, switch the virtual property on.

const list = new dhx.List("list_container", { 
virtual:true
});

Related sample: List. Virtual list

Editing items​

List with an item being edited inline showing selected highlighted text in DHTMLX Suite

Related sample: List. Inline editing

You can make List items editable with the help of the editable configuration option:

const list = new dhx.List("list_container", {editable:true});

Height of an item​

List with increased item height showing book titles and categories in DHTMLX Suite

Related sample: List. Setup list item height

You can specify the necessary height of an item and set it before List initialization via the itemHeight property either as a number:

// sets the height of an item as a number
const list = new dhx.List("list_container", {
itemHeight:30
});

or as a string value:

// sets the height of an item as a string value
const list = new dhx.List("list_container", {
itemHeight:"30px"
});
note

The usage of the CSS calc() function within the itemHeight property is not possible.

When the virtual property is set to true, the default height of a list item is 37. To change this value, make use of the itemHeight property, as described above.

Height of the List​

Scrollable List with a fixed height showing book titles and categories in DHTMLX Suite

Related sample: List. Setup list height

You can define the desired height of a list via the height configuration option:

const list = new dhx.List("list_container", {height: 700});

You can also use a string value to set the height of List:

const list = new dhx.List("list_container", {height: "700px"});
note

The usage of the CSS calc() function within the height property is not possible.

Multiple selection of items​

List with multiple selected book items highlighted at once in DHTMLX Suite

Related sample: List. Multiselection

By default, you can select only one item in a list, since selecting another item resets the previous selection. To select several List items, make use of the multiselection configuration option:

const list = new dhx.List("list_container", {multiselection:true});

Setting the multiselection property to true lets you select multiple items with the Ctrl key. It is also possible to use the "Ctrl+click" combination to select several items. For this, you need to set the multiselection configuration option to ctrlClick:

const list = new dhx.List("list_container", {
multiselection:"ctrlClick"
});

Selection of items​

List of books with titles, authors and categories without selection in DHTMLX Suite

Related sample: List. Disable selection

The default configuration of List provides you with the selection feature that allows you to highlight a List item. To disable selection in a List, set the selection configuration property to false:

const list = new dhx.List("list_container", {selection: false});

Template for List items​

List rendered with a custom HTML template showing book titles, authors and categories in DHTMLX Suite

Related sample: List. HTML template for item

You can define a template for rendering items in a List with the help of the template configuration property. Set its value to a function that takes one parameter:

  • item - (object) an object of a data item

const list = new dhx.List("list_container", {
css: "dhx_widget--bordered",
template: function(item) {
const template = "<div className='list_item'>";
template += "<div className='item_name'>"+item.value;

template+="<span className='item_author'> by "
template += item.authors.filter(function(item){return item}).join(", ");
template += item.publishedDate ? ", "
template += new Date(item.publishedDate.$date).getFullYear() : "";
template += "</span>";
template += "</div>";

template += "<div className='item_categories'>"+item.categories.join(", ")+"</div>";
template += "</div>";
return template;
},
itemHeight: 72
});

Event handlers for the template​

Starting from v7.0, it is possible to assign event handlers to HTML elements of a custom List item template by using the eventHandlers configuration option:

function template(item) {
let template = "<div className='list_item'>";
template += "<div className='item_name'>"+item.value;
template +="<span className='item_author'> by "
template += item.authors.filter(function(item){return item}).join(", ");
template += item.publishedDate ? ", "
template += new Date(item.publishedDate.$date).getFullYear() : "";
template += "</span>";
template += "</div>";
template += "<span className='item_categories'>"+item.categories.join(", ")+"</span>";
template += "</div>";
return template;
}

const list = new dhx.List("list_container", {
css: "dhx_widget--bordered",
template: template,
eventHandlers: {
onclick: {
list_item: function(event) {
console.log("You clicked on " + event.target.tagName);
},
},
onmouseover: {
list_item: function(event, id) {
console.log(list.data.getItem(id).value);
},
}
}
});

Related sample: List. Handling events in template

HTML content of List options​

By default, List displays HTML content if it is specified for its options.

If you need to disable rendering of HTML content and show it as plain text to keep your application safe, set the htmlEnable property to false.

const list = new dhx.List("list_container", {
htmlEnable: false, // disables render of HTML content
template: template,
data: data
});

Related sample: List. Disable HTML rendering