A newer version of this page is available. Switch to the current version.

ASPxGridLookup Class

An editor that allows end-users to easily select values from a dropdown grid containing lookup items.

Namespace: DevExpress.Web

Assembly: DevExpress.Web.v19.2.dll


public class ASPxGridLookup :
Public Class ASPxGridLookup
    Inherits ASPxDropDownEditBase
    Implements IControlDesigner


The ASPxGridLookup is a data-bound control that combines the functionality of the ASPxDropDownEdit and ASPxGridView controls. The ASPxGridView control is seamlessly embedded into the editor's dropdown window, providing the editor with powerful customizable data-processing and data-representation functionality. End-users can change the editor's value by simply selecting a row in the dropdown grid, or input new values into the editor's edit box.


To populate the built-in ASPxGridView with data, the ASPxGridLookup control should be bound to a data source using the ASPxGridLookup.DataSourceID or ASPxGridLookup.DataSource property.

The ASPxGridLookup control provides the ASPxGridLookup.Columns collection to store the columns of the built-in ASPxGridView. Data columns can be created automatically for each field in the data source when the ASPxGridLookup is rendered, or created manually. This is controlled by the ASPxGridLookup.AutoGenerateColumns property. If this property is set to true, the ASPxGridLookup renders each field from the data source as a data column within the built-in ASPxGridView (the order of columns is the same as the order of fields in the data source). To manually control which columns are to appear in the dropdown ASPxGridView, set the ASPxGridLookup.AutoGenerateColumns property to false. In this case, you should manually add data columns to the ASPxGridLookup.Columns collection and bind them to the corresponding data source fields.

The ASPxGridLookup editor supports single and multiple selection of list items within the dropdown grid through the ASPxGridLookup.SelectionMode property. Each selected item is displayed within the ASPxGridLookup's edit box, based upon a pattern defined by the ASPxGridLookup.TextFormatString property. This property contains indexed placeholders (such as "{0}", "{1}", etc.) which correspond to the indexes of visible columns whose values should be displayed within the edit box (placeholders can be combined with fixed literals). When multiple selection is used, the texts of selected rows are joined in the edit box using a special separator specified by the ASPxGridLookup.MultiTextSeparator property. (See online demo Multiple Record Selection)

The ASPxGridLookup allows data to be filtered within a dropdown grid by typing text in the editor's input box. Use the ASPxGridLookup.IncrementalFilteringMode property to specify the editor's filter mode. (See online demo Incremental Filtering)

The ASPxGridView embedded into the ASPxGridLookup control's dropdown window can be fully customized via settings exposed by the editor's ASPxGridLookup.GridViewProperties property.


When the ASPxGridLookup's ASPxEdit.Enabled property is set to false, the embedded ASPxGridView isn't bound to data and a dropdown window isn't rendered. This behavior is designed to reduce unnecessary markups when the editor is disabled. Thus, if you need a disabled ASPxGridLookup bound to data, use the ASPxEditBase.ClientEnabled property.


The client-side equivalent of this editor control is represented by the ASPxClientGridLookup object. The editor's client-side API is enabled if the ASPxEditBase.EnableClientSideAPI property is set to true, the ASPxEditBase.ClientInstanceName property is defined, or any client event is handled. Available client events can be accessed via the ASPxGridLookup.ClientSideEvents property.


The embedded ASPxGridView control caches its object properties. It can cause an exception when you use XPO or custom objects. To learn more, see the ASPxGridView.EnableRowsCache property description.

Refer to the ASPxGridLookup - Overview topic to learn more about the ASPxGridLookup control's features.


This example illustrates ho