Virtual Scroll
v1.1+

The QVirtualScroll component allows you to display only a part of a long list of items and update the visible items as the user scrolls in the container. This has several advantages: only visible items are rendered, so the smallest number of nodes are in the DOM tree at any given point in time and the memory consumption is kept at its lowest.

There are currently two types of QVirtualScroll: “list” (using QItems) and “table” (using a tabular style to display rows of data).

Installation


// quasar.conf.js

return {
  framework: {
    // NOT needed if using auto-import feature:
    components: [
      'QVirtualScroll'
    ]
  }
}

Usage

TIP

  • To get the best performance while using large lists freeze the array you are passing in the items prop using Object.freeze(items). This allows Vue to skip making the list “responsive” to changes.
  • The number of items that will be rendered will be calculated based on the virtual-scroll-item-size prop and the size of the scrolling container, but you can fit it to your needs using the virtual-scroll-slice-size prop.
  • Use the virtual-scroll-item-size to specify the size of elements (pixels of height or width, if horizontal). After an element is rendered on screen it’s size is updated automatically, but if you specify an element size close to the real size you’ll get a better initial indication of the scroll position. Regardless if you will be using this property or not, QVirtualScroll will still work, but without it you may experience the scrollbar not following the mouse grab position while continuously scrolling (on desktop) or the actual scroll of the container getting slightly off by one or two elements when on mobile and continuously scrolling.

WARNING

  • There is a maximum height of the scrolling container, imposed by the browser. In IE11 this is around 1,000,000px, while in the rest of the browsers it’s much more, but still limited.

Scroll the examples below to see QVirtualScroll in action.

Basic

Basic



Horizontal

Horizontal



Different templates

Different templates for items



Different templates for horizontal items



Table type

Notice the type="table" property.

Basic table



With header that scrolls along with content (doesn’t stay in place).

Table with scrolling header/footer



Notice (in the example below) the CSS required to make the table header and footer “sticky”. Also note the additional scoped slots which define the header and footer content.

WARNING

IE11 does not supports the sticky header/footer.

Sticky headers table



A more involved example below, playing with sticky headers and footers.

Playing with sticky headers



Scroll target

If you need to specify the scroll target (because the auto detected one is not the desired one) pass a CSS selector (as string) or the DOM element to the scroll-target prop.

If you need to use the virtual list with the whole page as the scrolling element then please set scroll-target="body".

WARNING

  • If you pass a custom scroll target container with scroll-target prop you must make sure that the element exists and that it can be overflowed (it must have a maximum height and an overflow that allows scrolling).
  • If the scroll target container cannot be overflowed you’ll get the whole list rendered.

WARNING

If you want to use a Vue reference for scroll-target, please take care to set it after mounting the component, like in the example below.

Custom scroll target by id



Custom scroll target by ref



Scroll to position

Scroll to position



Sync and async

You can also generate the items to be displayed on the list by using the items-fn prop.

WARNING

Make sure to use a synchronous function that returns the list of items to be displayed.

If you need async data use a component that retrieves and renders the data.

Generate items on the fly



QVirtualScroll API