Framework7 - Virtual List

---

---

Description

Virtual list is a type of list view, which includes large number of data elements without dropping their performance. You can create HTML layout of virtual list by using the virtual-list class along with the list-block class.

Initialize Virtual List

You can initialize the virtual list by using the following method −

myApp.virtualList(listBlockContainer, parameters)

The method contains the following parameters −

• listBlockContainer − It is a required HTML or string element for the list block container.

• parameters − It is a required object, which includes virtual list parameters.

Virtual List Parameters

The following table provides a list of virtual parameters −

Virtual List Properties

Virtual List Methods

Templating

Sometimes you need to filter or load the items from JSON data using some logic. To do this, you can pass array with data objects using items parameter and template parameter or using renderItem parameter.

You can use Framework7 template parameter as follows −

var myVal = myApp.virtualList('.list-block.virtual-list', {
   //List of array items
   items: [
      {
         name: 'Element 1',
         image: '/path/image1.jpg'
      },
      {
         name: 'Element 2',
         image: '/path/image2.jpg'
      },
      // ...
      {
         name: 'Element 50',
         image: '/path/image50.jpg'
      },
   ],
   
   // Display the each item using Template7 template parameter
   template: 
      '<li class = "item-content">' +
         '<div class = "item-media"><img src = "{{image}}"></div>' +
         '<div class = "item-inner">' +
            '<div class = "item-title">{{name}}</div>' +
         '</div>' +
      '</li>'
});

You can also use custom render function as shown below −

var myVal = myApp.virtualList('.list-block.virtual-list', {
   //List of array items
   items: [
      {
         name: 'Element 1',
         image: '/path/image1.jpg'
      },
      {
         name: 'Element 2',
         image: '/path/image2.jpg'
      },
      // ...
      {
         name: 'Element 50',
         image: '/path/image50.jpg'
      },
   ],
   
   // Display the each item using custom render function
   renderItem: 
      '<li class = "item-content">' +
         '<div class = "item-media"><img src = "{{image}}"></div>' +
         '<div class = "item-inner">' +
            '<div class = "item-title">{{name}}</div>' +
         '</div>' +
      '</li>'
});

Using With Search Bar

You can use searchAll or searchByItem parameters in order to use the search bar with virtual list that supply the search function in parameters.

var myVal = myApp.virtualList('.list-block.virtual-list', {
   //List of array items
   items: [
      {
         name: 'Element 1',
         image: '/path/image1.jpg'
      },
      {
         name: 'Element 2',
         image: '/path/image2.jpg'
      },
      // ...
      {
         name: 'Element 50',
         image: '/path/image50.jpg'
      },
   ],
   
   //Here you can searches all items in array and send back array with matched items
   searchAll: function (query, items) {
      var myItems = [];
      
         for (var i = 0; i < items.length; i++) {
            // Here check if name contains query string
            if (items[i].name.indexOf(query.trim()) >= 0) myItems.push(i);
         }
         
         // Returns array with indexes of matched items
         return myItems;
   }
});

Using searchByItem parameter −

var myVal = myApp.virtualList('.list-block.virtual-list', {
   //List of array items
   items: [
      {
         name: 'Element 1',
         image: '/path/image1.jpg'
      },
      {
         name: 'Element 2',
         image: '/path/image2.jpg'
      },
      // ...
      {
         name: 'Element 50',
         image: '/path/image50.jpg'
      },
   ],
   
   //Here you can searches all items in array and send back array with matched items
   searchByItem: function (query, index, items) {
      // Here check if name contains query string
         if (items[i].name.indexOf(query.trim()) >= 0){
            return true;
         }  else {
            return false;
         }
      }
   }
});

Dynamic Height

You can use dynamic height for the items by using the height parameter instead of a number.

var myVal = myApp.virtualList('.list-block.virtual-list', {
   //List of array items
   items: [
      {
         name: 'Element 1',
         image: '/path/image1.jpg'
      },
      {
         name: 'Element 2',
         image: '/path/image2.jpg'
      },
      // ...
      {
         name: 'Element 50',
         image: '/path/image50.jpg'
      },
   ],
   
   //template parameter
   template: '...',

   //using height function
   height: function (item) {
      if (item.image) return 120; //display the image with 100px height
      else return 50; //display the image with 50px height
   }
});

API Methods

You can use the API methods to add, remove, replace or move virtual list items.

//Here you can initialize the list
var myVal = myApp.virtualList('.list-block.virtual-list', {
   //List of array items
   items: [
      {
         name: 'Element 1',
         image: '/path/image1.jpg'
      },
      {
         name: 'Element 2',
         image: '/path/image2.jpg'
      },
      // ...
      {
         name: 'Element 50',
			image: '/path/image50.jpg'
      },
   ],
   //template parameter
   template: '...',
});

//Here append your item
myVal.appendItem({
    image: 'Element 55'
});

// You can append multiple items when clicking on button
$('.button.append-items').on('click', function () {
   //You can append multiple items by passing array with items
   myVal.appendItem ([
      {
         image: 'Element 60'
      },
      {
         image: 'Element 61'
      },
      {
         image: 'Element 62'
      }
   ]);
});

//replace the first item
myList.replaceItem(0, {
   name: 'Element 4'
});

//you can display first 10 items when clicking on button
$('.button.show-first-10').on('click', function () {
   //Passing array with indexes to show items
   myList.filter([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
});

//Reset the filter
$('.button.reset-filter').on('click', function () {
   myList.resetFilter();
});

//You can insert the item before 4th and 5th item
myList.insertItemBefore(1, {
   name: 'Element 4.5'
});