All Components

DropDownList Overview

The DropDownList is a form component that allows you to choose a single predefined value from a list.

It is a richer version of the <select> element that provides support for a default item, data binding, filtering, and templates.

Basic Usage

The following example demonstrates the DropDownList in action:

@Component({
  selector: 'my-app',
  template: `
    <kendo-dropdownlist [data]="listItems">
    </kendo-dropdownlist>
  `
})
class AppComponent {
    public listItems: Array<string> = ["Item 1", "Item 2", "Item 3", "Item 4"];
}

Configuration

Data Binding

The DropDownList enables you to bind data of primitive types such as strings and numbers as well as data inside objects. It also supports binding to an asynchronous source.

Bind to Arrays of Primitive Data

The example below demonstrates how to bind the DropDownList to an array of primitive data.

@Component({
  selector: 'my-app',
  template: `
    <kendo-dropdownlist [data]="listItems"></kendo-dropdownlist>
  `
})
class AppComponent {
    public listItems: Array<string> = [1, 2, 3];
}

Bind to Arrays of Complex Data

Define the textField and valueField properties when the component is bound to complex data (objects). The DropDownList will extract the value and text values from the selected data item and in this way will set the selected value and text.

The example below demonstrates how to bind the DropDownList to an array of complex data.

@Component({
  selector: 'my-app',
  template: `
    <kendo-dropdownlist
        [data]="listItems"
        [textField]="'text'"
        [valueField]="'value'"
    >
    </kendo-dropdownlist>
  `
})
class AppComponent {
    public listItems: Array<{ text: string, value: number }> = [
        { text: "Foo", value: 1 },
        { text: "Bar", value: 2 },
        { text: "Baz", value: 3 }
    ];
}

Default Item

The defaultItem property type has to match the data type. For example, if the data property contains a list of objects, the defaultItem has to be defined as an object with the same textField and valueField as the data items.

The example below demonstrates how to define a defaultItem as a primitive value.

@Component({
  selector: 'my-app',
  template: `
    <kendo-dropdownlist
        [defaultItem]="'Select...'"
        [data]="listItems"
        [valuePrimitive]="true"
    >
    </kendo-dropdownlist>
  `
})
class AppComponent {
    public listItems: Array<string> = [1, 2, 3];
}

The example below demonstrates how to define a defaultItem as an object value.

@Component({
  selector: 'my-app',
  template: `
    <kendo-dropdownlist
        [defaultItem]="defaultItem"
        [data]="listItems"
        [textField]="'text'"
        [valueField]="'value'"
    >
    </kendo-dropdownlist>
  `
})
class AppComponent {
    public defaultItem: { text: string, value: number } = { text: "Select...", value: null };

    public listItems: Array<{ text: string, value: number }> = [
        { text: "Foo", value: 1 },
        { text: "Bar", value: 2 },
        { text: "Baz", value: 3 }
    ];
}

Templates

To customize the list item, the selected value, the popup footer or header content, use the item, value, footer, and header templates.

Item Template

Use the item template to customize the content of every list item. To define an item template, nest a <template> tag with an itemTemplate directive inside <kendo-dropdownlist>.

The template context is set to the current DropDownList component. To get a reference to the current data item, use the let-dataItem directive.

@Component({
  selector: 'my-app',
  template: `
    <kendo-dropdownlist
        [data]="listItems"
        [textField]="'text'"
        [valueField]="'value'"
        [value]="selectedValue"
        [valuePrimitive]="true"
    >
        <template itemTemplate let-dataItem>
            {{ dataItem.text }} | {{ dataItem.value }}
        </template>
    </kendo-dropdownlist>
  `
})
class AppComponent {
    public listItems: Array<{ text: string, value: number }> = [
        { text: "Foo", value: 1 },
        { text: "Bar", value: 2 },
        { text: "Baz", value: 3 }
    ];

    public selectedValue: number = 2;
}

Value Template

Use the value template to customize the element content that holds the selected text. To define a value template, nest a <template> tag with a valueTemplate directive inside <kendo-dropdownlist>.

The template context is set to the current DropDownList component. To get a reference to the current data item, use the let-dataItem directive.

@Component({
  selector: 'my-app',
  template: `
    <kendo-dropdownlist
        [data]="listItems"
        [textField]="'text'"
        [valueField]="'value'"
        [value]="selectedValue"
        [valuePrimitive]="true"
    >
        <template valueTemplate let-dataItem>
            {{ dataItem?.text }} | {{ dataItem?.value }}
        </template>
    </kendo-dropdownlist>
  `
})
class AppComponent {
    public listItems: Array<{ text: string, value: number }> = [
        { text: "Foo", value: 1 },
        { text: "Bar", value: 2 },
        { text: "Baz", value: 3 }
    ];

    public selectedValue: number = 2;
}

Header Template

Use the header template to customize the popup header element. To define a header template, nest a <template> tag with a headerTemplate directive inside <kendo-dropdownlist>.

The template context is set to the current DropDownList component.

@Component({
  selector: 'my-app',
  template: `
    <kendo-dropdownlist
        [data]="listItems"
        [textField]="'text'"
        [valueField]="'value'"
        [value]="selectedValue"
        [valuePrimitive]="true"
    >
        <template headerTemplate>
            <h4>Header template</h4>
        </template>
    </kendo-dropdownlist>
  `
})
class AppComponent {
    public listItems: Array<{ text: string, value: number }> = [
        { text: "Foo", value: 1 },
        { text: "Bar", value: 2 },
        { text: "Baz", value: 3 }
    ];

    public selectedValue: number = 2;
}

Use the footer template to customize the popup footer element. To define a footer template, nest a <template> tag with a footerTemplate directive inside <kendo-dropdownlist>.

The template context is set to the current DropDownList component.

@Component({
  selector: 'my-app',
  template: `
    <kendo-dropdownlist
        [data]="listItems"
        [textField]="'text'"
        [valueField]="'value'"
        [value]="selectedValue"
        [valuePrimitive]="true"
    >
        <template footerTemplate>
            <h4>Footer template</h4>
        </template>
    </kendo-dropdownlist>
  `
})
class AppComponent {
    public listItems: Array<{ text: string, value: number }> = [
        { text: "Foo", value: 1 },
        { text: "Bar", value: 2 },
        { text: "Baz", value: 3 }
    ];

    public selectedValue: number = 2;
}

Value Selection

The DropDownList allows for defining its selected value as primitive (strings, numbers) or complex (objects). It depends on the valuePrimitive configuration option when to use which.

Specify the Value Type

To specify the value type, set the valuePrimitive property. By default, it is set to false—just like the defaultItem, the value has to match the data type.

If the valuePrimitive property is set to true, the value has to be of the primitive type.

@Component({
  selector: 'my-app',
  template: `
    <kendo-dropdownlist
        [data]="listItems"
        [textField]="'text'"
        [valueField]="'value'"
        [value]="selectedObject"
    >
    </kendo-dropdownlist>
    <kendo-dropdownlist
        [data]="listItems"
        [textField]="'text'"
        [valueField]="'value'"
        [value]="selectedPrimitive"
        [valuePrimitive]="true"
    >
    </kendo-dropdownlist>
  `
})
class AppComponent {
    public listItems: Array<{ text: string, value: number }> = [
        { text: "Foo", value: 1 },
        { text: "Bar", value: 2 },
        { text: "Baz", value: 3 }
    ];

    public selectedObject: { text: string, value: number } = { text: "Bar", value: 2 };
    public selectedPrimitive: number = 2;
}

Set the Value Property Binding

It is possible to set the value of the DropDownList through its [value] property binding. The component accepts values of the complex (objects) or the primitive (strings or numbers) type. To specify the value type, set the valuePrimitive property. By default, it is set to false—just like the defaultItem, the value has to match the data type.

When the value changes, the DropDownList executes the valueChange callback function.

The example below demonstrates how to select an item by using primitive values.

@Component({
  selector: 'my-app',
  template: `
    <kendo-dropdownlist
        [data]="listItems"
        [textField]="'text'"
        [valueField]="'value'"
        [value]="selectedValue"
        [valuePrimitive]="true"
    >
    </kendo-dropdownlist>
  `
})
class AppComponent {
    public listItems: Array<{ text: string, value: number }> = [
        { text: "Foo", value: 1 },
        { text: "Bar", value: 2 },
        { text: "Baz", value: 3 }
    ];

    public selectedValue: number = 2;
}

The example below demonstrates how to select an item by using complex values.

@Component({
  selector: 'my-app',
  template: `
    <kendo-dropdownlist
        [data]="listItems"
        [textField]="'text'"
        [valueField]="'value'"
        [value]="selectedValue"
    >
    </kendo-dropdownlist>
  `
})
class AppComponent {
    public listItems: Array<{ text: string, value: number }> = [
        { text: "Foo", value: 1 },
        { text: "Bar", value: 2 },
        { text: "Baz", value: 3 }
    ];

    public selectedValue: { text: string, value: number } = { text: "Bar", value: 2 };
}

Forms Support

It is possible to use the DropDownList in template-driven or reactive forms. The component accepts values of the complex (objects) or the primitive (strings or numbers) type. To specify the value type, set the valuePrimitive property. By default, it is set to false—just like the defaultItem, the value has to match the data type.

Template-Driven Forms

The template-driven forms enable you to bind the DropDownList to the model by using the ngModel directive.

The example below demonstrates how to accomplish a two-way data binding by using the ngModel directive. The model field is a complex value.

@Component({
  selector: 'my-app',
  template: `
    <fieldset>
        The Selected gender is {{ gender | json }}
    </fieldset>
    <fieldset>
        <label>
            Select Gender:
            <kendo-dropdownlist
                [data]="genders"
                [textField]="'text'"
                [valueField]="'value'"
                [(ngModel)]="gender"
            >
            </kendo-dropdownlist>
        </label>
    </fieldset>
  `
})
class AppComponent {
    public genders: Array<{ text: string, value: number }> = [
        { text: "Male", value: 1 },
        { text: "Female", value: 2 }
    ];

    public gender: { text: string, value: number } = { text: "Female", value: 2 };
}

The example below demonstrates how to accomplish a two-way data binding by using the ngModel directive. The model field is a primitive value.

@Component({
  selector: 'my-app',
  template: `
    <fieldset>
        The Selected gender is {{ gender | json }}
    </fieldset>
    <fieldset>
        <label>
            Select Gender:
            <kendo-dropdownlist
                [data]="genders"
                [textField]="'text'"
                [valueField]="'value'"
                [valuePrimitive]="true"
                [(ngModel)]="gender"
            >
            </kendo-dropdownlist>
        </label>
    </fieldset>
  `
})
class AppComponent {
    public genders: Array<{ text: string, value: number }> = [
        { text: "Male", value: 1 },
        { text: "Female", value: 2 }
    ];

    public gender: { text: string, value: number } = 2;
}

Reactive Forms

The FormGroup provides a way to render reactive forms. For more details, refer to the Angular Documentation.

The example below demonstrates how to use the DropDownList in a reactive form with a primitive value binding.  

import {
    FormsModule,
    ReactiveFormsModule,
    FormGroup,
    FormControl
} from '@angular/forms';

@Component({
  selector: 'my-app',
  template: `
    <form [formGroup]="myForm">
        <fieldset>
        The form.gender value is: {{myForm.controls.gender.value}}
        <br />
        The form is valid: {{myForm.controls.gender.valid}}
        </fieldset>
        <label>
            Select gender
            <kendo-dropdownlist
                formControlName="gender"
                [data]="genders"
                [textField]="'text'"
                [valueField]="'value'"
                [valuePrimitive]="true"
            >
            </kendo-dropdownlist>
        </label>
    </form>
  `
})
class AppComponent {
    public genders: Array<{ text: string, value: number }> = [
        { text: "Male", value: 1 },
        { text: "Female", value: 2 }
    ];

    public myForm: FormGroup = new FormGroup({
        gender: new FormControl(2)
    });
}

The example below demonstrates how to use the DropDownList in a reactive form with a complex value binding.  

import {
    FormsModule,
    ReactiveFormsModule,
    FormGroup,
    FormControl
} from '@angular/forms';

@Component({
  selector: 'my-app',
  template: `
    <form [formGroup]="myForm">
        <fieldset>
        The form.gender value is: {{myForm.controls.gender.value | json}}
        <br />
        The form is valid: {{myForm.controls.gender.valid}}
        </fieldset>
        <label>
            Select gender
            <kendo-dropdownlist
                formControlName="gender"
                [data]="genders"
                [textField]="'text'"
                [valueField]="'value'"
            >
            </kendo-dropdownlist>
        </label>
    </form>
  `
})
class AppComponent {
    public genders: Array<{ text: string, value: number }> = [
        { text: "Male", value: 1 },
        { text: "Female", value: 2 }
    ];

    public myForm: FormGroup = new FormGroup({
        gender: new FormControl({ text: "Female", value: 2 })
    });
}

Filtering

To enable the filtering functionality, set the filterable property to true. As a result, the component renders a filter input in the popup component. On every character input, the component triggers a filterChange event.

The event argument contains the typed string value and it is possible for you to use this value to filter the source.

@Component({
  selector: 'my-app',
  template: `
    <kendo-dropdownlist
        [data]="data"
        [filterable]="true"
        [textField]="'text'"
        [valueField]="'value'"
        (filterChange)="handleFilter($event)"
    >
    </kendo-dropdownlist>
  `
})
class AppComponent {
    public source: Array<{ text: string, value: number }> = [
        { text: "Foo", value: 1 },
        { text: "Bar", value: 2 },
        { text: "Baz", value: 3 }
    ];

    public data: Array<{ text: string, value: number }>;

    constructor() {
        this.data = this.source.slice();
    }

    handleFilter(value) {
        this.data = this.source.filter((s) => s.text.toLowerCase().indexOf(value.toLowerCase()) !== -1);
    }
}

Events

On Change of Item Selection

The selectionChange event is triggered when the item selection is changed.

@Component({
  selector: 'my-app',
  template: `
    <kendo-dropdownlist
        [data]="data"
        [textField]="'text'"
        [valueField]="'value'"
        (selectionChange)="handleSelection($event)"
    >
    </kendo-dropdownlist>
    <br />

    Last 10 calls:
    <ul>
        <li *ngFor="let call of eventCalls">{{ call.name }}: {{ call.value | json }}</li>
    </ul>
  `
})
class AppComponent {
    public data: Array<{ text: string, value: number }> = [
        { text: "Foo", value: 1 },
        { text: "Bar", value: 2 },
        { text: "Baz", value: 3 }
    ];

    public eventCalls: Array<any> = [];

    last10Calls() {
        const end = this.eventCalls.length;

        return this.eventCalls.slice(Math.max(0, end - 10), end);
    }

    handleSelection(value) {
        this.eventCalls = this.last10Calls().concat([ { name: 'select', value: value } ]);
    }
}

On Value Change

The valueChange event is triggered when the selected value is changed.

If the popup is open, the valueChange event will not fire. To raise the change event when the popup is still open, either blur the component or press ENTER.

@Component({
  selector: 'my-app',
  template: `
    <kendo-dropdownlist
        [data]="data"
        [textField]="'text'"
        [valueField]="'value'"
        (valueChange)="handleValue($event)"
    >
    </kendo-dropdownlist>
    <br />

    Last 10 calls:
    <ul>
        <li *ngFor="let call of eventCalls">{{ call.name }}: {{ call.value | json }}</li>
    </ul>
  `
})
class AppComponent {
    public data: Array<{ text: string, value: number }> = [
        { text: "Foo", value: 1 },
        { text: "Bar", value: 2 },
        { text: "Baz", value: 3 }
    ];

    public eventCalls: Array<any> = [];

    last10Calls() {
        const end = this.eventCalls.length;

        return this.eventCalls.slice(Math.max(0, end - 10), end);
    }

    handleValue(value) {
        this.eventCalls = this.last10Calls().concat([ { name: 'change', value: value } ]);
    }
}

On Filter Change

The filterChange event is raised when something is typed inside the filter input. For more details, refer to the section on filtering.

On Looping through Items

By default, it is possible to select a DropDownList item by pressing a keyboard key. For example, if the DropDownList items are Foo, Bar, and Baz, and the user presses the B letter key, the first of the DropDownList items, based on their alphabetical order, starting with a B will be selected.

The keyboard selection is available only if filtering is disabled.

In this article