optionLabel String | Object(default: "")

Define the text of the default empty item. If the value is an object, then the widget will use it as a valid data item. Note that the optionLabel will not be available if the widget is empty.

  • If optionLabel is an object, it needs to have at least dataValueField and dataTextField properties. Otherwise, widget will show undefined. Note that the very same optionLabel object will be passed to the valueTemplate. You need to ensure that all required by the valueTemplate properties are present in the optionLabel object.
  • Since Q1 2015 (2015.1.318), the option label is rendered as a separate header template. The benefits of this change are:
  • the widget's value will be empty string even when dataValueField and dataTextField options are equal or not defined
  • the widget will not throw an exception when a custom item template is used and optionLabel is string
  • option label has a separate template, that gives more freedom for customization
  • [Not relevant after Q1 2015] Widget's value will be equal to the optionLabel if the dataValueField and dataTextField options are equal or not defined

Example - specify optionLabel as a string

<input id="dropdownlist" />
    dataSource: ["Apples", "Oranges"],
    optionLabel: "Select a fruit..."

Example - specify optionLabel as an object

<input id="dropdownlist" />
    dataSource: [
        { productName: "Product 1", productId: 1 },
        { productName: "Product 2", productId: 2 }
    dataTextField: "productName",
    dataValueField: "productId",
    optionLabel: {
        productName: "Select a product...",
        productId: ""
In this article
Not finding the help you need? Improve this article