├── README.md ├── bower.json ├── examples ├── index.html └── style.css ├── package.json └── vlist.js /README.md: -------------------------------------------------------------------------------- 1 | ## Virtual DOM List 2 | 3 | This is a simple component that allows the developer to create very 4 | long lists (by list I mean a single column of rows) that perform extremely 5 | fast. It does so by loading just the part of the list showing up on the viewport, and by optimizing 6 | the amount of DOM operations and reflows. It also spends very little memory. 7 | 8 | The list could be done even faster by sacrificing the 'momentum' effect, but I 9 | decided to keep it since it is too big of a sacrifice for the sake of speed. 10 | 11 | ## Installation 12 | 13 | npm install virtual-list 14 | 15 | Or if you prefer bower: 16 | 17 | bower install virtual-list 18 | 19 | Of course it can also just be added to any JavaScript project since it consists of a 20 | single JavaScript file. 21 | 22 | ## Usage 23 | 24 | Each of the following snippets of code creates a virtual list that holds 1 milion 25 | rows: 26 | 27 | ```javascript 28 | // This will create a scrolling list of 300x300 with 10000 rows. It is necessary to specify 29 | // how tall each row is by setting the `itemHeight` prpoerty in the config object. In this 30 | // example, we set up a generator function that will generate each row on demand. 31 | var list = new ScrollableList({ 32 | w: 300, 33 | h: 300, 34 | itemHeight: 31, 35 | totalRows: 10000, 36 | generatorFn: function(row) { 37 | var el = document.createElement("div"); 38 | el.innerHTML = "ITEM " + row; 39 | el.style.borderBottom = "1px solid red"; 40 | el.style.position = "absolute" 41 | return el; 42 | } 43 | }); 44 | document.body.appendChild(list.container) 45 | 46 | // The code below will create an array of 10000 DOM elements beforehand and pass them to 47 | // the list. The Virtual list will then display them on demand. Of course, even if the 48 | // virtual list is smart about displaying them, this method fills up a lot of memory by 49 | // creating the elements before-hand. 50 | var bigAssList = []; 51 | for (var i = 0; i < 10000; i++) { 52 | var el = document.createElement("div"); 53 | el.classList.add("item"); 54 | el.innerHTML = "ITEM " + i; 55 | el.style.borderBottom = "1px solid red"; 56 | bigAssList.push(el); 57 | } 58 | 59 | var list = new ScrollableList({ 60 | w: 300, 61 | h: 300, 62 | items: bigAssList, 63 | itemHeight: 31 64 | }); 65 | document.body.appendChild(list.container) 66 | 67 | // The code below will create an array of 10000 strings beforehand and pass them to 68 | // the list. The Virtual list will then display them on demand. 69 | var bigAssList = []; 70 | for (var i = 0; i < 10000; i++) 71 | bigAssList.push("ITEM " + i); 72 | 73 | var list = new ScrollableList({ 74 | w: 300, 75 | h: 300, 76 | items: bigAssList, 77 | itemHeight: 31 78 | }); 79 | document.body.appendChild(list.container) 80 | ``` 81 | 82 | ## Caveats 83 | 84 | Firefox has a nasty bug (https://bugzilla.mozilla.org/show_bug.cgi?id=373875) 85 | that breaks any attempt of assigning big numerical values to css properties. 86 | Since the virtual list does exactly that to give the illusion of a very big list 87 | without actually loading the components, you might run into that bug for very big 88 | lists. Unfortunately, I haven't found a way to work around it yet. 89 | 90 | ## License 91 | 92 | The MIT License (MIT) 93 | 94 | Copyright (C) 2013 Sergi Mansilla 95 | 96 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 97 | 98 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 99 | 100 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 101 | -------------------------------------------------------------------------------- /bower.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "virtual-list", 3 | "version": "1.0.1", 4 | "main": "vlist.js", 5 | "ignore": [ 6 | ".jshintrc", 7 | "README.md" 8 | ], 9 | "dependencies": {}, 10 | "devDependencies": {} 11 | } -------------------------------------------------------------------------------- /examples/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | Virtual List demo 10 | 11 | 12 | 13 | 14 | 47 | 48 | 49 | -------------------------------------------------------------------------------- /examples/style.css: -------------------------------------------------------------------------------- 1 | body, html { 2 | padding: 0; 3 | margin: 0; 4 | height: 100%; 5 | width: 100%; 6 | min-height: 100%; 7 | min-width: 100%; 8 | } 9 | body { 10 | overflow: hidden; 11 | } 12 | 13 | @media 14 | only screen and (-webkit-min-device-pixel-ratio : 1.5), 15 | only screen and (min-device-pixel-ratio : 1.5) { 16 | /* Styles */ 17 | .container { 18 | width: 100%; 19 | height: 100%; 20 | min-height: 100%; 21 | } 22 | } 23 | 24 | .vrow { 25 | width: 100%; 26 | height: 30px; 27 | max-height: 30px; 28 | /*border-bottom: solid 1px #dbd9d9;*/ 29 | color: #000; 30 | margin: 0; 31 | } 32 | 33 | .vrow p { 34 | white-space: nowrap; 35 | overflow: hidden; 36 | text-overflow: ellipsis; 37 | border: none; 38 | margin: 0; 39 | color: #5b5b5b; 40 | /*font-size: 1.5rem;*/ 41 | } -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "virtual-list", 3 | "version": "1.0.1", 4 | "description": "Allows the developer to create massively long lists that perform extremely fast by loading just the part of the list showing up on the viewport, and by optimizing the amount of DOM operations and reflows.", 5 | "dependencies": {}, 6 | "devDependencies": {}, 7 | "keywords": [ 8 | "list", 9 | "buffer", 10 | "render", 11 | "html", 12 | "infinite", 13 | "virtual", 14 | "performance", 15 | "dom" 16 | ], 17 | "main": "./vlist.js.js", 18 | "bugs": { 19 | "url": "https://github.com/sergi/virtual-list/issues" 20 | }, 21 | "repository": { 22 | "type": "git", 23 | "url": "git://github.com/sergi/virtual-list.git" 24 | }, 25 | "author": "Sergi Mansilla ", 26 | "license": "MIT" 27 | } 28 | -------------------------------------------------------------------------------- /vlist.js: -------------------------------------------------------------------------------- 1 | /** 2 | * The MIT License (MIT) 3 | * 4 | * Copyright (C) 2013 Sergi Mansilla 5 | * 6 | * Permission is hereby granted, free of charge, to any person obtaining a copy 7 | * of this software and associated documentation files (the 'Software'), to deal 8 | * in the Software without restriction, including without limitation the rights 9 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 10 | * copies of the Software, and to permit persons to whom the Software is 11 | * furnished to do so, subject to the following conditions: 12 | * 13 | * The above copyright notice and this permission notice shall be included in 14 | * all copies or substantial portions of the Software. 15 | * 16 | * THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 19 | * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 21 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 22 | * SOFTWARE. 23 | */ 24 | 25 | 'use strict'; 26 | 27 | /** 28 | * Creates a virtually-rendered scrollable list. 29 | * @param {object} config 30 | * @constructor 31 | */ 32 | function VirtualList(config) { 33 | var width = (config && config.w + 'px') || '100%'; 34 | var height = (config && config.h + 'px') || '100%'; 35 | var itemHeight = this.itemHeight = config.itemHeight; 36 | 37 | this.items = config.items; 38 | this.generatorFn = config.generatorFn; 39 | this.totalRows = config.totalRows || (config.items && config.items.length); 40 | 41 | var scroller = VirtualList.createScroller(itemHeight * this.totalRows); 42 | this.container = VirtualList.createContainer(width, height); 43 | this.container.appendChild(scroller); 44 | 45 | var screenItemsLen = Math.ceil(config.h / itemHeight); 46 | // Cache 4 times the number of items that fit in the container viewport 47 | this.cachedItemsLen = screenItemsLen * 3; 48 | this._renderChunk(this.container, 0); 49 | 50 | var self = this; 51 | var lastRepaintY; 52 | var maxBuffer = screenItemsLen * itemHeight; 53 | var lastScrolled = 0; 54 | 55 | // As soon as scrolling has stopped, this interval asynchronouslyremoves all 56 | // the nodes that are not used anymore 57 | this.rmNodeInterval = setInterval(function() { 58 | if (Date.now() - lastScrolled > 100) { 59 | var badNodes = document.querySelectorAll('[data-rm="1"]'); 60 | for (var i = 0, l = badNodes.length; i < l; i++) { 61 | self.container.removeChild(badNodes[i]); 62 | } 63 | } 64 | }, 300); 65 | 66 | function onScroll(e) { 67 | var scrollTop = e.target.scrollTop; // Triggers reflow 68 | if (!lastRepaintY || Math.abs(scrollTop - lastRepaintY) > maxBuffer) { 69 | var first = parseInt(scrollTop / itemHeight) - screenItemsLen; 70 | self._renderChunk(self.container, first < 0 ? 0 : first); 71 | lastRepaintY = scrollTop; 72 | } 73 | 74 | lastScrolled = Date.now(); 75 | e.preventDefault && e.preventDefault(); 76 | } 77 | 78 | this.container.addEventListener('scroll', onScroll); 79 | } 80 | 81 | VirtualList.prototype.createRow = function(i) { 82 | var item; 83 | if (this.generatorFn) 84 | item = this.generatorFn(i); 85 | else if (this.items) { 86 | if (typeof this.items[i] === 'string') { 87 | var itemText = document.createTextNode(this.items[i]); 88 | item = document.createElement('div'); 89 | item.style.height = this.itemHeight + 'px'; 90 | item.appendChild(itemText); 91 | } else { 92 | item = this.items[i]; 93 | } 94 | } 95 | 96 | item.classList.add('vrow'); 97 | item.style.position = 'absolute'; 98 | item.style.top = (i * this.itemHeight) + 'px'; 99 | return item; 100 | }; 101 | 102 | /** 103 | * Renders a particular, consecutive chunk of the total rows in the list. To 104 | * keep acceleration while scrolling, we mark the nodes that are candidate for 105 | * deletion instead of deleting them right away, which would suddenly stop the 106 | * acceleration. We delete them once scrolling has finished. 107 | * 108 | * @param {Node} node Parent node where we want to append the children chunk. 109 | * @param {Number} from Starting position, i.e. first children index. 110 | * @return {void} 111 | */ 112 | VirtualList.prototype._renderChunk = function(node, from) { 113 | var finalItem = from + this.cachedItemsLen; 114 | if (finalItem > this.totalRows) 115 | finalItem = this.totalRows; 116 | 117 | // Append all the new rows in a document fragment that we will later append to 118 | // the parent node 119 | var fragment = document.createDocumentFragment(); 120 | for (var i = from; i < finalItem; i++) { 121 | fragment.appendChild(this.createRow(i)); 122 | } 123 | 124 | // Hide and mark obsolete nodes for deletion. 125 | for (var j = 1, l = node.childNodes.length; j < l; j++) { 126 | node.childNodes[j].style.display = 'none'; 127 | node.childNodes[j].setAttribute('data-rm', '1'); 128 | } 129 | node.appendChild(fragment); 130 | }; 131 | 132 | VirtualList.createContainer = function(w, h) { 133 | var c = document.createElement('div'); 134 | c.style.width = w; 135 | c.style.height = h; 136 | c.style.overflow = 'auto'; 137 | c.style.position = 'relative'; 138 | c.style.padding = 0; 139 | c.style.border = '1px solid black'; 140 | return c; 141 | }; 142 | 143 | VirtualList.createScroller = function(h) { 144 | var scroller = document.createElement('div'); 145 | scroller.style.opacity = 0; 146 | scroller.style.position = 'absolute'; 147 | scroller.style.top = 0; 148 | scroller.style.left = 0; 149 | scroller.style.width = '1px'; 150 | scroller.style.height = h + 'px'; 151 | return scroller; 152 | }; 153 | --------------------------------------------------------------------------------