Skip to content

Small, efficient, type-safe virtual list for Vue 3

License

Notifications You must be signed in to change notification settings

bsssshhhhhhh/vue-typed-virtual-list

Repository files navigation

vue-typed-virtual-list

npm size vue3 Typescript

A fast, type-safe virtual list component for rendering massive data. Works with Vue 3

Live Demo · Try it on CodeSandbox

Features:

  • Extremely efficient calculations
  • Provides generic type safety inside the #item slot
  • Automatically and transparently deals with variable element heights
  • Small footprint. <10KB gzipped, including dependencies

Usage

Example:

<template>
  <div>
    <VirtualScroller
      :default-size="40"
      :items="someArrayOfUsers"
    >
      <template #item="{ ref, offset, index }">
        <!-- `ref` is the array item. Thanks to Volar, `ref` has the type `User` here -->

        {{ ref.name }}
      </template>
    </VirtualScroller>
  </div>
</template>

<script lang="ts">
import { defineComponent } from 'vue';
import { createVirtualScroller } from 'vue-typed-virtual-list';

type User = {
  id: number;
  name: string;
  phone: string;
};

export default defineComponent({
  components: {
    // pass the item type as a type parameter to enable type safety in the item slot
    VirtualScroller: createVirtualScroller<User>()
  },
  data: () => ({
    someArrayOfUsers: Array
      .from(Array(100))
      .map((_, i) => ({
        id: i + 1,
        name: 'Name',
        phone: 'Phone'
      }))
  })
})
</script>

or, with <script setup>:

<script setup lang="ts">
import { createVirtualScroller } from 'vue-typed-virtual-list';

const VirtualScroller = createVirtualScroller<User>();

type User = {
  id: number;
  name: string;
  phone: string;
};

const someArrayOfUsers: User[] = Array
  .from(Array(100))
  .map((_, i) => ({
    id: i + 1,
    name: 'Name',
    phone: 'Phone'
  }));

</script>

JavaScript Usage

If you're not using TypeScript in your project:

-const VirtualScroller = createVirtualScroller<User>();
+const VirtualScroller = createVirtualScroller();

Props

  • defaultSize - Placeholder size to use in calculations before an item's actual height has been measured
  • items - Array of items to render
  • padding - Number of items beyond what is visible in the overflow viewport to render. (Default: 10)

Emits

  • visibleItemsChanged - Fired when the start/end indices have changed
    • argument type: { start: number; end: number }

Exposed Instance Methods

  • scrollTo(index: number): void - scrolls an index into view (Example)

Development

yarn
yarn dev

Contributing

PRs welcome