Virtualization in EJ2 TypeScript ListView control

28 Jan 202520 minutes to read

UI virtualization loads only the viewable list items within a viewport, significantly improving ListView performance when dealing with a large amount of data.

Module injection

To use UI virtualization, you should import the Virtualization module from the ej2-lists package and inject it using the ListView.Inject() method, as shown in the following code snippet.

import { ListView, Virtualization } from '@syncfusion/ej2-lists';

ListView.Inject(Virtualization);

Getting started

UI virtualization can be enabled in the ListView by setting the enableVirtualization property to true.

There are two types of scroll behaviors:

Window Scroll: This is used by default in the ListView.

Container Scroll: This is used when the height property of the ListView is set.

index.ts
index.html
index.css
import { ListView, Virtualization } from '@syncfusion/ej2-lists';

ListView.Inject(Virtualization);

let listData: { [key: string]: string | object }[] = [
    { text: 'Nancy', id: '0', },
    { text: 'Andrew', id: '1' },
    { text: 'Janet', id: '2' },
    { text: 'Margaret', id: '3' },
    { text: 'Steven', id: '4' },
    { text: 'Laura', id: '5' },
    { text: 'Robert', id: '6' },
    { text: 'Michael', id: '7' },
    { text: 'Albert', id: '8' },
    { text: 'Nolan', id: '9' }
];

for (let i: number = 10; i <= 1010; i++) {
    let index: number = parseInt((Math.random() * 10).toString());
    listData.push({ text: listData[index].text, id: i.toString() });
}

let listObj: ListView = new ListView({

    //Set defined data to dataSource property.
    dataSource: listData,
    //Set height
    height: 500,
    //enable UI virtualization
    enableVirtualization: true,
});

listObj.appendTo('#ui-list');
<!DOCTYPE html>
<html lang="en">

<head>
    <title>Essential JS 2 for ListView </title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="description" content="Essential JS 2 for ListView UI Control" />
    <meta name="author" content="Syncfusion" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-base/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-lists/styles/material.css" rel="stylesheet" />
    <link href="index.css" rel="stylesheet" />
    <script src="https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.38/system.js"></script>
    <script src="systemjs.config.js"></script>
<script src="https://cdn.syncfusion.com/ej2/syncfusion-helper.js" type ="text/javascript"></script>
</head>

<body>
    <div id='loader'>Loading....</div>
    <div id='container'>
        <div id='ui-list'></div>
    </div>
    <style>
        #ui-list {
            display: block;
            max-width: 350px;
            margin: auto;
            border-radius: 3px;
            cursor: pointer;
        }
    </style>
</body>

</html>
#container {
    visibility: hidden;
}

#loader {
  color: #008cff;
  height: 40px;
  width: 30%;
  position: absolute;
  font-family: 'Helvetica Neue','calibiri';
  font-size: 14px;
  top: 45%;
  left: 45%;
}

You can use the template property to customize list items in UI virtualization.

index.ts
index.html
index.css
import { ListView, Virtualization } from '@syncfusion/ej2-lists';

ListView.Inject(Virtualization);

let listData: { [key: string]: string | object }[] = [
    { name: 'Nancy', icon: 'N', id: '0', },
    { name: 'Andrew', icon: 'A', id: '1' },
    { name: 'Janet', icon: 'J', id: '2' },
    { name: 'Margaret', imgUrl: '//ej2.syncfusion.com/demos/src/listview/images/margaret.png', id: '3' },
    { name: 'Steven', icon: 'S', id: '4' },
    { name: 'Laura', imgUrl: '//ej2.syncfusion.com/demos/src/listview/images/laura.png', id: '5' },
    { name: 'Robert', icon: 'R', id: '6' },
    { name: 'Michael', icon: 'M', id: '7' },
    { name: 'Albert', imgUrl: '//ej2.syncfusion.com/demos/src/listview/images/albert.png', id: '8' },
    { name: 'Nolan', icon: 'N', id: '9' }
]

for (let i: number = 10; i <= 1010; i++) {
    let index: number = parseInt((Math.random() * 10).toString());
    listData.push({ name: listData[index].name, icon: listData[index].icon, imgUrl: listData[index].imgUrl, id: i.toString() });
}

var template: Function = (data: any) => {
    var result = `<div class="e-list-wrapper e-list-avatar" >` +
        `<span class="e-avatar e-avatar-circle ${data.icon} ${data.imgUrl ? 'hideUI' : 'showUI'}">${data.icon}</span> <img class="e-avatar e-avatar-circle ${data.imgUrl ? 'showUI' : 'hideUI'}" ` +
        `src="${data.imgUrl ? data.imgUrl : ' '}" />` +
        `<span class="e-list-content">${data.name}</span></div>`;
    return result;
};

let listObj: ListView = new ListView({

    //Set defined data to dataSource property.
    dataSource: listData,

    //enable UI virtualization
    enableVirtualization: true,

    //Set height
    height: 500,

    //Set header title
    headerTitle: 'Contacts',

    //Set true to show header title
    showHeader: true,
    cssClass: 'e-list-template',

    //Set defined customized template
    template: template

});

listObj.appendTo('#ui-list');
<!DOCTYPE html>
<html lang="en">

<head>
    <title>Essential JS 2 for ListView </title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="description" content="Essential JS 2 for ListView UI Control" />
    <meta name="author" content="Syncfusion" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-base/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-lists/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-layouts/styles/material.css" rel="stylesheet" />
    <link href="index.css" rel="stylesheet" />
    <script src="https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.38/system.js"></script>
    <script src="systemjs.config.js"></script>
<script src="https://cdn.syncfusion.com/ej2/syncfusion-helper.js" type ="text/javascript"></script>
</head>

<body>
    <div id='loader'>Loading....</div>
    <div id='container'>
        <div id='ui-list'></div>
    </div>
    <style>
        #ui-list.e-listview {
            margin: auto;
            max-width: 325px;
            line-height: initial;
            border: 1px solid lightgray;
        }

        #ui-list.e-listview .e-list-header {
            height: 50px
        }

        #ui-list.e-listview .e-list-header .e-text {
            line-height: 18px
        }

        #ui-list.e-listview .R {
            background: lightgrey;
        }

        #ui-list.e-listview .M {
            background: pink;
        }

        #ui-list.e-listview .A {
            background: lightgreen;
        }

        #ui-list.e-listview .S {
            background: lightskyblue;
        }

        #ui-list.e-listview .J {
            background: orange;
        }

        #ui-list.e-listview .N {
            background: lightblue;
        }

        #ui-list.e-listview .e-list-item {
            padding: 3px 0;
        }

        #ui-list .list-container {
            width: inherit;
            height: 100%;

        }

        #ui-list.e-listview .showUI {
            display: flex;
        }

        #ui-list.e-listview .hideUI {
            display: none;
        }
    </style>
</body>

</html>
#container {
    visibility: hidden;
}

#loader {
    color: #008cff;
    height: 40px;
    width: 30%;
    position: absolute;
    font-family: 'Helvetica Neue','calibiri';
    font-size: 14px;
    top: 45%;
    left: 45%;
  }

Conditional rendering

The following conditional rendering support is provided for the template and groupTemplate.

Name	Syntax
conditional class	`<div class="${ $id % 2 === 0 ? 'even-list' : 'odd-list'}"></div>`
conditional attribute	`<div id="${ $id % 2 === 0 ? 'even-list' : 'odd-list'}"></div>`
conditional text content	`<div>${ $id % 2 === 0 ? 'even-list' : 'odd-list'}</div>`

In the following sample, the light blue is applied for the even list and light coral is applied for the odd list based on the conditional class.

index.ts
index.html
index.css
import { ListView, Virtualization } from '@syncfusion/ej2-lists';

ListView.Inject(Virtualization);

let listData: { [key: string]: string | object }[] = [];

listData = [
    { text: 'Nancy', id: '0', },
    { text: 'Andrew', id: '1' },
    { text: 'Janet', id: '2' },
    { text: 'Margaret', id: '3' },
    { text: 'Steven', id: '4' },
    { text: 'Laura', id: '5' },
    { text: 'Robert', id: '6' },
    { text: 'Michael', id: '7' },
    { text: 'Albert', id: '8' },
    { text: 'Nolan', id: '9' }
];

for (let i: number = 10; i <= 1010; i++) {
    let index: number = parseInt((Math.random() * 10).toString());
    listData.push({ text: listData[index].text, id: i.toString() });
}

let listObj: ListView = new ListView({

    //Set defined data to dataSource property.
    dataSource: listData,

    //enable UI virtualization
    enableVirtualization: true,

    //Set height
    height: 500,

    //Set defined customized template
    template: '${if(id % 2=="0")}<div id="list-container" class="even-list"> ${text} </div>${else}<div id="list-container" class="odd-list"> ${text} </div>${/if}'
});

listObj.appendTo('#ui-list');
<!DOCTYPE html>
<html lang="en">

<head>
    <title>Essential JS 2 for ListView </title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="description" content="Essential JS 2 for ListView UI Control" />
    <meta name="author" content="Syncfusion" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-base/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-lists/styles/material.css" rel="stylesheet" />
    <link href="index.css" rel="stylesheet" />
    <script src="https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.38/system.js"></script>
    <script src="systemjs.config.js"></script>
<script src="https://cdn.syncfusion.com/ej2/syncfusion-helper.js" type ="text/javascript"></script>
</head>

<body>
    <div id='loader'>Loading....</div>
    <div id='container'>
        <div id='ui-list'></div>
    </div>
    <style>
        #ui-list {
            display: block;
            max-width: 350px;
            margin: auto;
            border: 1px solid #dddddd;
            border-radius: 3px;
            cursor: pointer;
        }

        #list-container {
            height: inherit;
            width: inherit;
            padding-left: 30px;
        }

        #ui-list .e-list-item {
            padding: 0;
        }

        #ui-list .even-list {
            background-color: #cfd8dc;
        }

        #ui-list .odd-list {
            background-color: #eceff1;
        }
    </style>
</body>

</html>
#container {
    visibility: hidden;
}

#loader {
  color: #008cff;
  height: 40px;
  width: 30%;
  position: absolute;
  font-family: 'Helvetica Neue','calibiri';
  font-size: 14px;
  top: 45%;
  left: 45%;
}