Configuration

Disabled mode

You can disable Combobox and block all operations with it. Use the disabled configuration property:

const combo = new dhx.Combobox("combo_container", {
    disabled: true
});

Related sample: Combobox. Disabled

Dynamic rendering of options

Combobox loads all options at once. If you have a large data collection, render the data in portions instead. Use the virtual property to render options in the Combobox list dynamically as the user scrolls it:

const combo = new dhx.Combobox("combo_container", {
    virtual:true
});

Related sample: Combobox. Virtual list

Height of list of options and its items

Related sample: Combobox. List height

Use listHeight and itemHeight properties to adjust the height of the option list and the height of a single item in it:

const combo = new dhx.Combobox("combo_container", {
    listHeight:300,
    itemHeight:50
});

Help icon

A Combobox in a form often needs a hint about the options a user can select. Use the helpMessage configuration option and set the hint text as its value:

const combobox = new dhx.Combobox("combo_container", {
    helpMessage:"Some text"
});

Hidden label

When you send a form to the server, you can add a label that stays invisible but identifies the Combobox input on the server side. Use the hiddenLabel configuration property:

const combo = new dhx.Combobox("combo_container",{
    label:"My Combo",
    hiddenLabel:true
});

Initial value

Starting from v7.0, you can define the values that appear in the input during component initialization. Set them with the value property:

const combobox = new dhx.Combobox("combo_container", {
    multiselection: true,
    value: ["austria", "estonia"]
});

// or
const combobox = new dhx.Combobox("combo_container", {
    value: "austria"
});

Related sample: Combobox. Initial value

The value that the property accepts depends on the multiselection configuration:

• If you set multiselection:true, the property takes an array of option ids: for example, value: ["id_1","id_2","id_3"] or value: [1, 2, 3].
• If you set multiselection:false or omit the multiselection config, the property takes a single id or an array with one id: value:"id_1", value: 1, or value: ["id_1"].

Label

Use label, labelWidth, and labelPosition properties to set a label for Combobox and adjust the label width and position:

const combo = new dhx.Combobox("combo_container",{
    label:"Label",
    labelPosition: "left",
    labelWidth: 100
});

To place the label above the input:

const combo = new dhx.Combobox("combo_container",{
    label:"Label",
    labelPosition: "top",
    labelWidth: 100
});

Related sample: Combobox. Label position

Number of selected options

Related sample: Combobox. Items count

Instead of showing all selected options separately in the Combobox input, you can group them and display only the number of selected options. Use the itemsCount property.

The property accepts two types of values. You can enable the default behavior of the option, or specify a custom template function that displays the grouped options in a custom way. The function takes one parameter:

• count — (number) the number of selected options

The function must return the template that displays the result:

const combo = new dhx.Combobox("combo_container", {
    multiselection: true,
    // simply enables the option
    itemsCount: true
});

// or

const combo = new dhx.Combobox("combo_container", {
    multiselection: true,
    // set a custom template function for showing total number of selected options
    itemsCount: function (num) {
        return num + (num === 1 ? " item" : " items") + " selected";
    }
});

note

Enable the multiselection option to select several options at once.

Placeholder

Related sample: Combobox. Placeholder

To add a placeholder to the Combobox input, apply the placeholder property:

const combobox = new dhx.Combobox("combo_container",{
    placeholder: "Some placeholder"
});

Editable combobox

You can allow users to add new items to the data collection from the UI. Set the newOptions property to true:

const combobox = new dhx.Combobox("combo_container", {
    multiselection: true,
      newOptions: true  
});

To add a new item to the list of options, the user types a new value in the input field and then either presses Enter or clicks the Create "newValue" option that appears in the drop-down list.

Related sample: Combobox. Multiselection, add new options (free text), select all button

Combobox invokes beforeAdd and afterAdd events of DataCollection each time the user enters a new value in the input field. Use the beforeAdd event to reject incorrect values:

// blocks the ability to add an item with value: "new" into the collection of combobox items
combobox.data.events.on("beforeAdd", item => item.value !== "new");

You can also let users edit and delete items from the user interface. Use event handlers for the HTML elements in a custom template for Combobox items.

Related sample: Combobox. Editing/deleting options

Readonly mode

Related sample: Combobox. Readonly

You can make Combobox readonly with the readOnly property. Users then cannot type in the input and can only select options from the popup list:

const combo = new dhx.Combobox("combo_container",{
    readOnly:true
});

Selection of multiple options

To select several options in Combobox at once, use the multiselection configuration option:

const combo = new dhx.Combobox("combo_container", {
    multiselection:true
});

Selection of all options in the list

The Select All button selects all options in the Combobox list. To add this button to the component, use the selectAllButton property. The button also requires multiple selection, so set the multiselection configuration option to true:

const combo = new dhx.Combobox("combo_container", {
    // enables multiple selection of options
    multiselection:true,
    // shows the Select All button
    selectAllButton: true
});

Related sample: Combobox. Multiselection, add new options (free text), select all button

Template for Combobox options

Related sample: Combobox. HTML template

Use the template property to specify the appearance of Combobox options in the list. The property is a function that takes a data collection item as a parameter and returns a string with the template for rendering options:

const combo = new dhx.Combobox("combo_container", {
    template: function (item) {
      return "<div style='display:inline-block'>"
      +"<img style='width:20px;height:20px;margin-right:10px;' src="+item.src+"/></div>" 
      + item.value + "</div>";
    }
});            

Event handlers for the template

Starting from v8.4, you can assign event handlers to the HTML elements in a custom template for Combobox items. Use the eventHandlers configuration option:

const combobox = new dhx.Combobox("combobox", {
    newOptions: true, // enables the ability to add and save new values from UI
    itemHeight: 40,
    template: ({ value, src }) => {
        return `
            <div className="list-item">
                <div className="list-item__content">
                    <img className="list-item__image" src="${src}" alt="${value}"/>
                    <span className="list-item__value">${value}</span>
                </div>
                <button className="list-item__button list-item__button--delete">
                    <i className="dxi dxi-delete-forever"></i>
                </button>
            </div>
        `;
    },
    eventHandlers: {
        onclick: { 
            "list-item__button--delete": (event, id) => {
                combobox.data.remove(id);
                combobox.clear();    
            } 
        } 
    }
});

Related sample: Combobox. HTML template and handling events

HTML content of Combobox options

The default Combobox behavior is to display the HTML content specified for its options.

To disable HTML rendering and show the content as plain text to keep your application safe, set the htmlEnable property to false:

const combo = new dhx.Combobox("combo_container", { 
    htmlEnable: false, // disables rendering of HTML content
    template: function (item) {
        return "<div style='user-select:none; display: flex; justify-content: space-between;'>" +
            "<span>" + item.value + "</span>" +
            "<img style='height: 20px; width: 30px; border: 1px solid gray' src=" + item.src + "/></img>" +
            "</div>";
    }
});

Related sample: Combobox. Disable HTML rendering