New to Kendo UI for jQuery? Start a free 30-day trial

Virtual

configuration

Enables the virtualization feature of the widget. The configuration can be set on an object, which contains two properties - itemHeight and valueMapper.

For detailed information, refer to the article on virtualization.

virtual

Boolean|Object

Default: false

<input id="orders" style="width: 400px" />
<script>
    $(document).ready(function() {
        $("#orders").kendoAutoComplete({
            template: "#= OrderID # | For: #= ShipName #, #= ShipCountry #",
            dataTextField: "ShipName",
            virtual: true,
            height: 520,
            dataSource: {
                type: "odata-v4",
                transport: {
                    read: "https://demos.telerik.com/service/v2/odata/Orders"
                },
                schema: {
                    model: {
                        fields: {
                            OrderID: { type: "number" },
                            Freight: { type: "number" },
                            ShipName: { type: "string" },
                            OrderDate: { type: "date" },
                            ShipCity: { type: "string" }
                        }
                    }
                },
                pageSize: 80,
                serverPaging: true,
                serverFiltering: true
            }
        });
    });
</script>

<div class="demo-section k-header">
    <h4>Search for shipping name</h4>
    <input id="orders" style="width: 400px"
           data-role="autocomplete"
           data-bind="value: order, source: source"
           data-text-field="ShipName"
           data-virtual="{itemHeight:26,valueMapper:orderValueMapper}"
           />
</div>

<script>
    $(document).ready(function() {
        var model = kendo.observable({
          order: "Hanari Carnes",
          source: new kendo.data.DataSource({
            type: "odata-v4",
            transport: {
              read: "https://demos.telerik.com/service/v2/odata/Orders"
            },
            schema: {
              model: {
                fields: {
                  OrderID: { type: "number" },
                  Freight: { type: "number" },
                  ShipName: { type: "string" },
                  OrderDate: { type: "date" },
                  ShipCity: { type: "string" }
                }
              }
            },
            pageSize: 80,
            serverPaging: true,
            serverFiltering: true
          })
        });

        kendo.bind($(document.body), model);
    });

    function orderValueMapper(options) {
        $.ajax({
          url: "https://demos.telerik.com/service/v2/core/Orders/ValueMapper",
          type: "GET",
          data: convertValues(options.value),
          success: function (data) {
            options.success(data);
          }
        })
    }

    function convertValues(value) {
        var data = {};

        value = Array.isArray(value) ? value : [value];

        for (var idx = 0; idx < value.length; idx++) {
            data["values[" + idx + "]"] = value[idx];
        }

        return data;
    }
</script>

Specifies the height of the virtual item. All items in the virtualized list must have the same height. If the developer does not specify one, the framework will automatically set itemHeight based on the current theme and font size.

Default: null

<input id="orders" style="width: 400px" />
<script>
    $(document).ready(function() {
        $("#orders").kendoAutoComplete({
            template: "#= OrderID # | For: #= ShipName #, #= ShipCountry #",
            dataTextField: "ShipName",
            virtual: {
                itemHeight: 26
            },
            height: 520,
            dataSource: {
                type: "odata-v4",
                transport: {
                    read: "https://demos.telerik.com/service/v2/odata/Orders"
                },
                schema: {
                    model: {
                        fields: {
                            OrderID: { type: "number" },
                            Freight: { type: "number" },
                            ShipName: { type: "string" },
                            OrderDate: { type: "date" },
                            ShipCity: { type: "string" }
                        }
                    }
                },
                pageSize: 80,
                serverPaging: true,
                serverFiltering: true
            }
        });
    });
</script>

virtual.mapValueTo

String

The changes introduced with the Kendo UI R3 2016 release enable you to determine if the valueMapper must resolve a value to an index or a value to a dataItem. This is configured through the mapValueTo option that accepts two possible values - "index" or "dataItem". By default, the mapValueTo is set to "index", which does not affect the current behavior of the virtualization process.

For more information, refer to the article on virtualization.

Default: "index"

<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
    dataTextField: "ProductName",
    dataSource: {
        transport: {
            read: "https://demos.telerik.com/service/v2/core/Products"
        },
        serverFiltering: true
    },
    virtual: {
        itemHeight: 26,
        valueMapper: function(options) {
            // Custom value mapping logic
            console.log("Value mapper called with:", options.value);
            options.success(options.value);
        },
        mapValueTo: "dataItem" // Map to dataItem instead of index
    }
});
</script>

virtual.valueMapper

Function

Important

As of the Kendo UI R3 2016 release, the implementation of the valueMapper function is not necessary.

Default: null

// the example is relevant to Kendo UI versions prior to 2016.3.914
<input id="orders" style="width: 400px" />
<script>
    $(document).ready(function() {
        $("#orders").kendoAutoComplete({
            template: '<span class="order-id">#= OrderID #</span> #= ShipName #, #= ShipCountry #',
            dataTextField: "ShipName",
            virtual: {
                itemHeight: 26,
                valueMapper: function(options) {
                    $.ajax({
                        url: "https://demos.telerik.com/service/v2/core/Orders/ValueMapper",
                        type: "GET",
                        data: convertValues(options.value),
                        success: function (data) {
                            //the **data** is either index or array of indices.
                            //Example:
                            // "Ernst Handel" -> 10 (index in the Orders collection)
                            // ["Ernst Handel", "Que Delícia"] -> [10, 14] (indices in the Orders collection)

                            options.success(data);
                        }
                    })
                }
            },
            height: 520,
            dataSource: {
                type: "odata-v4",
                transport: {
                    read: "https://demos.telerik.com/service/v2/odata/Orders"
                },
                pageSize: 80,
                serverPaging: true,
                serverFiltering: true
            }
        });
    });

    function convertValues(value) {
        var data = {};

        value = Array.isArray(value) ? value : [value];

        for (var idx = 0; idx < value.length; idx++) {
            data["values[" + idx + "]"] = value[idx];
        }

        return data;
    }
</script>

Virtual

virtual

virtual.itemHeight

virtual.mapValueTo

virtual.valueMapper