Performant Lists and Tables in Vue.js with vue-virtual-scroller

After you have a basic Vue.js project created, start by installing the plugin from npm:

$ npm install -D vue-virtual-scroller

Then, in your main.js file you must include its CSS file and initialize it:

import "vue-virtual-scroller/dist/vue-virtual-scroller.css";
import Vue from "vue";
import VueVirtualScroller from "vue-virtual-scroller";

Vue.use(VueVirtualScroller);
// ...

That should be enough to start using it.

To start with a simple example, let’s create a plain list that takes lots of data and uses vue-virtual-scroller to render it.

Let’s use JSON-Generator to generate the JSON for 5000 entries and save it to a data.json file. You can use the following structure:

[
  '{{repeat(5000)}}',
  {
    _id: '{{objectId()}}',
    age: '{{integer(20, 40)}}',
    name: '{{firstName()}} {{surname()}}',
    company: '{{company().toUpperCase()}}'
  }
]

Let’s create a VirtualList.vue file, where we import data.json and add it to an items component state property. Then, use the <virtual-scroller> component, passing those items:

<template>
  <virtual-scroller :items="items" item-height="40" content-tag="ul">
    <template slot-scope="props">
      <li :key="props.itemKey">{{props.item.name}}</li>
    </template>
  </virtual-scroller>
</template>

<script>
import items from "./data.json";

export default {
  data: () => ({ items })
};
</script>

We must set an item-height to the virtual-scroller component. Alternatively, since we’re creating a list, we’ve set the content-tag="ul" which will wrap the contents into a <ul> tag.

vue-virtual-scroller allows to use scoped slots to render the contents for full flexibility with the rendering. By using slot-scope="props" we have access to the virtual-scroller exposed data, and use it for rendering.

props contains an itemKey property that we should bind using :key="props.itemKey" on the root of the content for performance reasons. Then we can access props.item containing the raw item from the JSON we’ve passed through the items property to virtual-scroller.

If you’d like to style the elements in the list, you can add a class attribute to the virtual-scroller component, and access its contents:

<template>
  <virtual-scroller class="virtual-list" ...></virtual-scroller>
</template>

<style>
.virtual-list ul {
  list-style: none;
}
</style>

Or, with scoped styles, use the /deep/ selector:

<style scoped>
.virtual-list /deep/ ul {
  list-style: none;
}
</style>

Similar to the VirtualList component, let’s create a VirtualTable.vue file for a table:

<template>
  <virtual-scroller :items="items" item-height="40" content-tag="table">
    <template slot-scope="props">
      <tr :key="props.itemKey">
        <td>{{props.item.age}}</td>
        <td>{{props.item.name}}</td>
        <td>{{props.item.company}}</td>
      </tr>
    </template>
  </virtual-scroller>
</template>

<script>
import items from "./data.json";

export default {
  data: () => ({ items })
};
</script>

We encounter a problem with this example; we want to add a <thead> tag as the table header in order to show the columns names: Age, Name and Company.

Fortunately, virtual-scroller distributes its internal content using the following slots structure:

<main>
  <slot name="before-container"></slot>
  <container>
    <slot name="before-content"></slot>
    <content>
      <!-- Your items here -->
    </content>
    <slot name="after-content"></slot>
  </container>
  <slot name="after-container"></slot>
</main>

Any of those slots can be used to place contents in there. container will be replaced by the tag value of the container-tag property, by default div, and the content by the content-tag value.

It’s therefore easy to add a thead using the before-content slot:

<template>
  <virtual-scroller
    :items="items"
    item-height="40"
    container-tag="table"
    content-tag="tbody"
    >
      <thead slot="before-content">
        <tr>
          <td>Age</td>
          <td>Name</td>
          <td>Company</td>
        </tr>
      </thead>
      <template slot-scope="props">
        <tr :key="props.itemKey">
          <td>{{props.item.age}}</td>
          <td>{{props.item.name}}</td>
          <td>{{props.item.company}}</td>
        </tr>
      </template>
  </virtual-scroller>
</template>

Notice that we’ve changed content-tag="table" for container-tag="table" and content-tag="tbody" in order to keep a usual table structure, since now we’re using more elements.

I’m sure you can imagine how to add a tfoot element as well 😉.

We’ve used the vue-virtual-scroller plugin to create components for a VirtualList and a VirtualTable. If you try them out with the 5000 items we’ve generated, they should render and scroll quite smoothly. Check vue-virtual-scroller docs to see more options and customizations.

You can see the working code of the article in this Codesandox.

Stay cool 🦄