This is an overview of the most common usage of ListView. For more information about the available properties, methods, or events, head over to the complete API documentation for ListView.

<ListView> is a UI component that shows items in a vertically scrolling list. To set how the list shows individual items, you can use the <v-template> component.

<ListView for="item in listOfItems" @itemTap="onItemTap">
    <!-- Shows the list item label in the default color and style. -->
    <Label :text="item.text" />

Using <ListView> with multiple <v-template> blocks

The v-template component is used to define how each list item is shown on the screen.

If you need to visualize one or more list items differently than the rest, you can enclose them in additional <v-template> blocks and use conditions. You can have as many <v-template> blocks as needed within one <ListView>.

<ListView for="item in listOfItems" @itemTap="onItemTap"> 
    <Label :text="item.text" /> 

  <v-template if="$odd">
    <!-- For items with an odd index, shows the label in red. -->
    <Label :text="item.text" color="red" />

When you create conditions for <v-template>, you can use a valid JavaScript expression with the following variables:

  • $index— the index of the current item
  • $eventrue if the index of the current item is even
  • $oddtrue if the index of the current item is odd
  • item— the item of the list (the name corresponds to the iterator in the for property). E.g. if="item.text == 'danger'"

Only the above variables are available in this scope, and currently you do not have access to the component scope (component state, computed properties...).

An important note about v-for

<ListView> does not loop through list items as you would expect when using a v-for loop. Instead <ListView> only creates the necessary views to display the currently visible items on the screen, and reuses the views that are already off-screen when scrolled. This concept is called view recycling and is commonly used in mobile apps to improve performance.

This is important, because you should not use key properties within your v-templates, as they will force the ListView to re-create the views and prevent view recycling from working properly.

To use multiple event listeners within a ListView, you can pass in the current item to the listener with @tap="onTap(item, $event)".

Check out this playground with multiple buttons in each ListView cell

If you only need to handle taps on the whole cell, you can use the itemTap event which contains the index of the tapped item and the actual item from the list.

onItemTap(event) {

NOTE: If a v-for is used on a <ListView> a warning will be printed to the console, and it will be converted to the for property.


forStringProvides the expression for iterating through the items.
For example:
  • item in listOfItems
  • (item, index) in listOfItems
  • item in [1, 2, 3, 4, 5]
itemsArray<any>An array of items to be shown in the <ListView>.
This property is only for advanced use. Use the for property instead.
separatorColorColorSets the separator line color. Set to transparent to remove it.


itemTapEmitted when an item in the <ListView> is tapped. To access the tapped item, use event.item.


refresh()Forces the <ListView> to reload all its items.

Native component