cyp178 / vue-virtual-scroll-grid

A Vue 3 component that can render a list with 1000+ items as a grid in a performant way.

Virtual Scroll Grid for Vue 3

This is a reusable component for Vue 3 that renders a list with a huge number of items (e.g. 1000+ items) as a grid in a performant way.

• Demo
• NPM Package

Features

• Use virtual-scrolling / windowing to render the items, so the number of DOM nodes is kept low.
• Just use CSS grid to style your grid. Minimum styling opinions form the library.
• Support using a paginated API to load the items in the background.
• Support rendering placeholders for unloaded items.
• Support both vertical and horizontal scroll.
• Loaded items are cached for better performance.

Code Examples

• As an ES module (with a bundler)
• As a Universal Module Definition (no bundler)

Install

npm install vue-virtual-scroll-grid

Available Props

Name	Description	Type	Validation
length	The number of items in the list	number	Required, an integer greater than or equal to 0
pageProvider	The callback that returns a page of items as a promise. pageNumber start with 0	(pageNumber: number, pageSize: number) => Promise<unknown[]>	Required
pageSize	The number of items in a page from the item provider (e.g. a backend API)	number	Required, an integer greater than or equal to 1
pageProviderDebounceTime	Debounce window in milliseconds on the calls to pageProvider	number	Optional, an integer greater than or equal to 0, defaults to 0
probeTag	The HTML tag used as probe element. Default value is div	string	Optional, any valid HTML tag, defaults to div
respectScrollToOnResize	Snap to the position set by scrollTo when the grid container is resized	boolean	Optional, defaults to false
scrollBehavior	The behavior of scrollTo. Default value is smooth	smooth | auto	Optional, a string to be smooth or auto, defaults to smooth
scrollTo	Scroll to a specific item by index	number	Optional, an integer from 0 to the length prop - 1, defaults to 0
tag	The HTML tag used as container element. Default value is div	string	Optional, any valid HTML tag, defaults to div
getKey	The :key used on each grid item. Auto-generated, but overwritable via function	(internalItem: InternalItem) => number | string 1	Optional, any valid Function that returns a string or number

Example:

<Grid
  :length="1000"
  :pageProvider="async (pageNumber, pageSize) => Array(pageSize).fill('x')"
  :pageSize="40"
  :scrollTo="10"
>
<!-- ...slots -->
</Grid>

Available Slots

There are 3 scoped slots: default, placeholder and probe.

The default slot

The default slot is used to render a loaded item.

Props:

• item: the loaded item that is used for rendering your item element/component.
• index: the index of current item within the list.
• style: the style object provided by the library that need to be set on the item element/component.

Example:

<template v-slot:default="{ item, style, index }">
  <div :style="style">{{ item }} {{ index }}</div>
</template>

Theplaceholder slot

When an item is not loaded, the component/element in the placeholder slot will be used for rendering. The placeholder slot is optional. If missing, the space of unloaded items will be blank until they are loaded.

Props:

• index: the index of current item within the list.
• style: the style object provided by the library that need to be set on the item element/component.

Example:

<template v-slot:placeholder="{ index, style }">
  <div :style="style">Placeholder {{ index }}</div>
</template>

The probe slot

The probe slot is used to measure the visual size of grid item. It has no prop. You can pass the same element/component for the placeholder slot. If not provided, you must set a fixed height to grid-template-rows on your CSS grid, e.g. 200px. If provided, make sure it is styled with the same dimensions as rendered items in the default or placeholder slot. Otherwise, the view wouldn't be rendered properly, or the rendering could be very slow.

Example:

<template v-slot:probe>
  <div class="item">Probe</div>
</template>

Exposed Public Properties

• allItems: All items memoized by the grid

Scroll Mode

The library uses grid-auto-flow CSS property to infer scroll mode. Set it to column value if you want to enable horizontal scroll.

Caveats

The library does not require items have foreknown width and height, but do require them to be styled with the same width and height under a view. E.g. the items can be 200px x 200px when the view is under 768px and 300px x 500px above 768px.

Development

Required environment variables:

• VITE_APP_ID: An Algolia app ID
• VITE_SEARCH_ONLY_API_KEY: The search API key for the Algolia app above

• Setup: npm install
• Run dev server: npm run dev
• Lint (type check): npm run lint
• Build the library: npm run build
• Build the demo: npm run build -- --mode=demo
• Preview the locally built demo: npm run serve

How to Release a New Version

We use semantic-release to release the library on npm automatically.