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

BaseListBoxControl.CustomizeItem Event

Allows you to dynamically customize templated items.

Namespace: DevExpress.XtraEditors

Assembly: DevExpress.XtraEditors.v19.1.dll


public event CustomizeTemplatedItemEventHandler CustomizeItem

Event Data

The CustomizeItem event's data class is CustomizeTemplatedItemEventArgs. The following properties provide information specific to this event:

Property Description
DataItem Gets the current item’s underlying data object. For a bound ListBoxControl, the DataItem property returns the corresponding record in the data source.
Index Gets the current item’s visual position. For a bound ListBoxControl, this property’s value matches the index of a corresponding record in the data source.
TemplatedItem Gets the template used to render the current item. Customize this template when handling the BaseListBoxControl.CustomizeItem event.
Value Gets the item’s value.


A ListBox control can render its items based on an item template that you can create at design time or in code with the BaseListBoxControl.Templates property.

The CustomizeItem event fires for each templated ListBox item that is about to be displayed. Handle this event to dynamically modify the rendering of certain items.

A template typically consists of one or more elements, each of which can display text and/or image. When handling the CustomizeItem event, you can access template elements with the e.TemplatedItem.Elements collection and modify their text, image, alignment and appearance settings.


This example shows how to use the BaseListBoxControl.CustomizeItem event to dynamically change the visibility and appearance of item elements for a templated ListBoxControl, which is bound to a data source.

The default template that is about to be customized contains four elements.


Three elements (‘CompanyName’, ‘Country’ and ‘City’) are bound to existing fields in the data source, and thus obtain their values automatically. The ‘countryflag’ template element is not bound to any existing field in the bound data source, and thus is not auto-populated with data at runtime by default. If you run the application without additionally customizing the template, you get the following result.


This example handles the BaseListBoxControl.CustomizeItem event to customize individual listbox items:

  • Change elements’ foreground color
  • Provide images for the ‘countryflag’ element
  • Hide text in specific elements

The image below demonstrates the result.


static Image flagGermany = Image.FromFile(@"c:\Data\germanyflag.png");
static Image flagSweden = Image.FromFile(@"c:\Data\swedenflag.png");

Dictionary<string, Color> countrycolors = new Dictionary<string, Color>() {
    {"Germany", Color.Black },
    {"Mexico", Color.Green },
    {"UK", Color.Red }

Dictionary<string, Image> countryFlags = new Dictionary<string, Image>() {
    { "Germany", flagGermany},
    { "Sweden", flagSweden}

private void listBoxControl1_CustomizeItem(object sender, DevExpress.XtraEditors.CustomizeTemplatedItemEventArgs e) {
    DataRowView row = e.DataItem as DataRowView;
    if (row == null) return;
    // Get the currently processed 'Country'
    string country = row["Country"].ToString(); 
    Color countrycolor = Color.Gray;
    if (countrycolors.ContainsKey(country)) {
        countrycolor = countrycolors[country];
        foreach (TemplatedItemElement element in e.TemplatedItem.Elements) {
            //Set a foreground color for all elements
            element.Appearance.Normal.ForeColor = countrycolor; 
    if (country == "Germany" || country == "Sweden") {
        // Display a custom image in the 'countryflag' template element
        TemplatedItemElement countryflag = e.TemplatedItem.Elements["countryflag"];
        countryflag.ImageOptions.Image = countryFlags[country];
        countryflag.ImageOptions.ImageScaleMode = DevExpress.XtraEditors.TileItemImageScaleMode.Stretch;
        // Hide the 'Country' element's text portion
        e.TemplatedItem.Elements["Country"].Text = ""; 
See Also