{"id":12463,"library":"vue-draggable-virtual-scroll-list","title":"Vue Draggable Virtual Scroll List","description":"This `vue-draggable-virtual-scroll-list` package is a Vue 2 component designed to combine the drag-and-drop capabilities of `SortableJS/Vue.Draggable` with the performance benefits of `tangbc/vue-virtual-scroll-list` for rendering large datasets. It allows developers to create sortable lists that efficiently handle a significant number of items by only rendering the visible elements, while still supporting intuitive drag-and-drop interactions. Currently at version 0.0.15, the project appears to be in an early development phase, suggesting potential for rapid changes. Its primary differentiation lies in offering a pre-integrated solution for two common UI challenges in Vue 2: managing large lists and enabling sortability, bypassing the need for manual integration of these complex libraries. It explicitly lists Vue 2.6.14 or higher as a peer dependency, firmly placing it within the Vue 2 ecosystem.","status":"active","version":"0.0.15","language":"javascript","source_language":"en","source_url":"https://github.com/p-baleine/vue-draggable-virtual-scroll-list","tags":["javascript","typescript"],"install":[{"cmd":"npm install vue-draggable-virtual-scroll-list","lang":"bash","label":"npm"},{"cmd":"yarn add vue-draggable-virtual-scroll-list","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-draggable-virtual-scroll-list","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for any Vue 2 project using this component.","package":"vue","optional":false}],"imports":[{"note":"The component is typically imported as a named export. While the package ships TypeScript types, CommonJS 'require' syntax is not the idiomatic way to import components in modern Vue CLI setups, though it might appear in older or non-bundled Vue 2 projects.","wrong":"const DraggableVirtualList = require('vue-draggable-virtual-scroll-list');","symbol":"DraggableVirtualList","correct":"import { DraggableVirtualList } from 'vue-draggable-virtual-scroll-list';"},{"note":"The 'Item' component for rendering individual list items is a user-defined Vue component, passed as a prop to DraggableVirtualList. It is not imported from the package itself.","symbol":"Item","correct":"const Item = { /* ... */ };"}],"quickstart":{"code":"import Vue from 'vue';\nimport { DraggableVirtualList } from 'vue-draggable-virtual-scroll-list';\n\n// Define the individual item component\nconst Item = {\n  props: {\n    source: {\n      type: Object,\n      default: () => ({}),\n    },\n  },\n  template: `\n    <div class=\"phrase\" :key=\"source.id\" style=\"padding: 10px; border-bottom: 1px solid #eee; background-color: white;\">\n      {{ source.content }}\n    </div>\n  `,\n};\n\nnew Vue({\n  el: '#app',\n  components: {\n    DraggableVirtualList,\n  },\n  data() {\n    const items = [];\n    // Generate a large number of items for virtualization demo\n    for (let i = 0; i < 1000; i++) {\n      items.push({\n        id: i,\n        content: `Item ${i + 1} - Drag me!`, // Example content\n      });\n    }\n    return {\n      items: items,\n      Item: Item, // Pass the local Item component to the DraggableVirtualList\n    };\n  },\n  template: `\n    <div id=\"app\">\n      <h2>Draggable Virtual List Example</h2>\n      <p>Drag and drop items in this list. It efficiently handles 1000 items.</p>\n      <draggable-virtual-list\n        class=\"phrase-list\"\n        v-model=\"items\"\n        :size=\"50\"           // Estimated height of each item in pixels\n        :keeps=\"20\"          // Number of items to keep rendered outside the viewport\n        :data-key=\"'id'\"     // Unique key for each item in the data source\n        :data-sources=\"items\" // Data source for the virtual list\n        :data-component=\"Item\" // Component to render each item\n        style=\"height: 400px; overflow-y: auto; border: 1px solid #ccc;\"\n      >\n      </draggable-virtual-list>\n    </div>\n  `,\n});","lang":"javascript","description":"This example demonstrates how to set up `DraggableVirtualList` in a Vue 2 application, providing a sortable, virtualized list of 1000 items. It shows how to pass data, configure item height, and specify the individual item component."},"warnings":[{"fix":"Always review the GitHub repository's commit history or examples for specific changes when updating to a new version.","message":"This package is currently in an early development phase (v0.0.15) and does not strictly adhere to semantic versioning. Any minor version update may introduce breaking changes without prior notice.","severity":"breaking","affected_versions":">=0.0.1"},{"fix":"For Vue 3 projects, seek out alternative libraries like `vue-virtual-sortable` or the Vue 3 compatible versions of `vuedraggable` and `vue-virtual-scroll-list`.","message":"This component is built specifically for Vue 2 applications and is incompatible with Vue 3 due to fundamental changes in the Vue API and its underlying dependencies (`vuedraggable` and `vue-virtual-scroll-list` each have Vue 3 specific versions).","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Ensure each item in your `items` array has a unique property (e.g., `id`) and set `:data-key=\"'id'\"`.","message":"The component requires a `:data-key` prop which must correspond to a unique identifier on each item in your data array. Failure to provide a unique key can lead to inconsistent rendering or incorrect drag-and-drop behavior.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Always bind both `v-model` and `:data-sources` to the same array reference, e.g., `v-model=\"items\" :data-sources=\"items\"`.","message":"Both `v-model` and `:data-sources` props are used to bind the list data. While `v-model` is primarily for updating the list order after a drag operation, `:data-sources` is used by the underlying virtual list for rendering. Ensure both are correctly bound to the same data array to avoid inconsistencies.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Experiment with `:size` to accurately match your item's actual height in pixels and adjust `:keeps` to find a balance between smooth scrolling and memory usage.","message":"Optimal performance of the virtual scroll list depends heavily on correctly setting the `:size` (estimated height of each item) and `:keeps` (number of items to keep rendered outside the viewport) props. Incorrect values can lead to choppy scrolling, rendering issues, or excessive DOM elements.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you have `import { DraggableVirtualList } from 'vue-draggable-virtual-scroll-list'` and added it to your Vue instance's `components` option: `components: { DraggableVirtualList }`.","cause":"The component was not properly imported or registered in your Vue instance.","error":"Failed to resolve component: DraggableVirtualList"},{"fix":"Verify that each item in your `v-model` array has a unique `id` property and that `:data-key` is correctly set to this property (e.g., `:data-key=\"'id'\"`). Ensure your `data-component` structure is stable and not causing unexpected re-renders or DOM manipulation.","cause":"Often occurs when the underlying virtual list or draggable library fails to access DOM elements due to incorrect item keys, dynamic rendering issues, or a mutable list being directly manipulated outside of `v-model` setters.","error":"Cannot read property 'getBoundingClientRect' of null (or similar errors related to DOM elements not found or inconsistent rendering)"},{"fix":"Check that your `v-model` is correctly bound to your data array, `:data-key` points to a unique identifier, and your `data-component` correctly exposes the `source` prop for individual items to facilitate reordering.","cause":"Usually caused by misconfiguration of the `vuedraggable` part of the component, such as incorrect `v-model` binding, missing unique `data-key`, or issues with the structure/props of your `data-component`.","error":"Drag-and-drop does not work, items are not reordered, or drag ghosts appear incorrectly."}],"ecosystem":"npm"}