JavaScript Virtual Scrolling Library for Large Lists and Infinite Scroll

Scroll through 10,000 items below. Only the visible rows exist in the DOM at any time, open your browser DevTools and inspect the list while scrolling to see it in action.

10 000 rows - itemHeight: 50 - bufferSize: 3 - adaptiveOverscan: true

Use it whenever you need to display a long list or table without slowing down the browser. It is a good fit for data grids, search results, chat windows, activity feeds, product catalogs, log viewers, and any interface that loads large amounts of rows.

• Handles huge lists - renders 1,000,000+ items without the page freezing.
• Low memory usage - only the visible rows exist in the DOM, so memory stays flat no matter how large the dataset grows.
• Smooth scrolling - updates are throttled to one render per animation frame for a steady 60 frames per second.
• No framework, no build step - drop in one script file and it works.
• Flexible - supports fixed or variable row heights, DOM recycling, infinite scroll, and chat-style reverse mode.
• Accessible - adds ARIA list and listitem roles automatically.
• Free and open source - released under the MIT license for personal and commercial use.

Most popular virtual scrolling libraries are tied to a specific framework. hcg-virtual-scroll takes the opposite approach: it is plain JavaScript, so it works in React, Vue, Svelte, or no framework at all, with the same API everywhere.

Direct Script Include

Download the files and reference them in your HTML. This is the simplest way to get started - no build tools needed.

<link rel="stylesheet" href="hcg-virtual-scroll.css" />
<script src="hcg-virtual-scroll.js"></script>

After the script loads, the global HCGVirtualScroll class is available on the window object.

NPM Usage

Install the package with npm or yarn.

npm install hcg-virtual-scroll

Then import it into your project. The library supports CommonJS and ES module style imports.

// CommonJS
const HCGVirtualScroll = require('hcg-virtual-scroll');

// ES Module
import HCGVirtualScroll from 'hcg-virtual-scroll';

import 'hcg-virtual-scroll/hcg-virtual-scroll.css';

Remember to also include the stylesheet from the package in your build or HTML.

CDN Usage

Load the library directly from a CDN without installing anything.

<!-- Stylesheet -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/hcg-virtual-scroll/hcg-virtual-scroll.css" />

<!-- Script -->
<script src="https://cdn.jsdelivr.net/npm/hcg-virtual-scroll/hcg-virtual-scroll.js"></script>

An unpkg link works the same way.

<link rel="stylesheet" href="https://unpkg.com/hcg-virtual-scroll/hcg-virtual-scroll.css" />
<script src="https://unpkg.com/hcg-virtual-scroll/hcg-virtual-scroll.js"></script>

Quick Start

Create a container element with a fixed height, then initialize the library with your data array and a renderItem function.

<div id="myList" class="hcg-vs-parent" style="height: 400px;"></div>

Initialise:

// sample data - 10,000 items
const data = [];
for (let i = 0; i < 10000; i++) {
  data.push({ id: i, name: 'Item ' + i });
}

// initialize virtual scroll
const vs = new HCGVirtualScroll(data, {
  container:  '#myList',
  itemHeight: 50,
  renderItem: function(item, index) {
    return '<div class="row">#' + index + ' - ' + item.name + '</div>';
  }
});

What is renderItem?

renderItem is a function you write that controls how each row looks on screen. It receives two arguments, item, which is one object from your data array, and index, which is the position number. Inside the function, you access your data fields directly using item.yourFieldName and return them as an HTML string. Every visible row in the list is built by calling this function once per item.

renderItem: function(item, index) {
  return `<div class="row"> ${index} - ${item.name} - ${item.email} </div>`;
}

hcg-virtual-scroll is released under the MIT License - free for personal and commercial use.

HCGVirtualScroll accepts any plain JavaScript array. There are no required field names, no special format, and no conversion needed. Whatever your data looks like, just pass it in and access the fields inside renderItem.

Any array works

Array of objects (most common):

const users = [
  { id: 1, name: 'Malik', email: 'Malik@example.com', role: 'Admin'  },
  { id: 2, name: 'Anvar', email: 'Anvar@example.com', role: 'Member' },
  { id: 3, name: 'Jhon', email: 'Jhon@example.com', role: 'Member' },
  // ... hundreds or thousands more
];

const vs = new HCGVirtualScroll(users, {
  container:  '#userList',
  itemHeight: 56,
  emptyText: 'No results found',
  renderItem(item, index) {
    return `<div class="row">
      <span>${index + 1}</span>
      <span>${item.name}</span>
      <span>${item.email}</span>
      <span>${item.role}</span>
    </div>`;
  },
});

Array of strings:

const countries = ['Afghanistan', 'Albania', 'Algeria', 'Andorra', 'Angola'];

const vs = new HCGVirtualScroll(countries, {
  container:  '#countryList',
  itemHeight: 44,
  emptyText: 'No results found',
  renderItem(item, index) {
    return `<div class="row">${index + 1}. ${item}</div>`;
  },
});

Array of numbers:

const prices = [9.99, 14.99, 4.50, 29.99, 1.00];

const vs = new HCGVirtualScroll(prices, {
  container:  '#priceList',
  itemHeight: 44,
  emptyText: 'No results found',
  renderItem(item, index) {
    return `<div class="row">#${index} - $${item.toFixed(2)}</div>`;
  },
});

Loading Data from an API

Fetch your data first, then create the instance. Or create an empty instance immediately and call updateData when the data arrives, useful for showing a loading state.

// Create empty, fill when ready
var vs = new HCGVirtualScroll([], {
  container: '#userList',
  itemHeight: 56,
  emptyText: 'No results found',
  loadingHTML: `<div class="my-spinner">Loading...</div>`,
  renderItem: function (user) {
    return '<div class="row">' + user.name + ' - ' + user.email + '</div>';
  },
});

vs.showLoading(); // show loading, block render

fetch('https://jsonplaceholder.typicode.com/users')
  .then(function (res) { return res.json(); })
  .then(function (users) {
    vs.updateData(users); // sets the data internally - render still blocked
    vs.hideLoading(); // unblocks render, shows data
  });

How showLoading and hideLoading Work Together

While showLoading() is active, all rendering is paused. Scroll events, resize events, and any internal render calls are blocked until hideLoading() is called. This prevents blank or incomplete content from flashing on screen while data is still being fetched.

updateData() can be called while loading is still active, it stores the new data internally even though the render is paused. When hideLoading() is called, the list renders immediately with the correct data already in place.

Always call updateData() before hideLoading(). Calling hideLoading() first causes the empty state to appear for a brief moment before the data renders.

Correct order:

vs.showLoading();

fetch('/api/items')
  .then(res => res.json())
  .then(data => {
    vs.updateData(data);  // store data first
    vs.hideLoading();     // then reveal
  });

Wrong order. causes empty state flicker:

vs.hideLoading();   // renders with no data - empty state appears
vs.updateData(data); // renders again with real data

// User applies a filter - pass the new filtered array
function applyFilter(keyword) {
  const filtered = allItems.filter(item =>
    item.name.toLowerCase().includes(keyword.toLowerCase())
  );
  vs.updateData(filtered);
}

// User sorts - pass the sorted array
function sortByName() {
  const sorted = [...allItems].sort((a, b) => a.name.localeCompare(b.name));
  vs.updateData(sorted);
}

Required Options

Both of the following options are required. The instance will throw an error if either is missing.

Optional Options

Loading & Empty State

Config & Lifecycle

All callbacks are optional. Pass them as properties of the options object when creating the instance, or add them later with updateConfig.

onScroll(scrollTop, range)

Fires on every scroll event, throttled to one call per animation frame.

onScroll: function(scrollTop, range) {
  console.log('Scrolled to ' + scrollTop + 'px');
  console.log('Visible: ' + range.start + ' to ' + range.end);
}

onVisibleRangeChange({ start, end })

Fires only when the rendered range of items actually changes, not on every scroll pixel. Use this to react to which items are on screen without processing every scroll event.

onVisibleRangeChange: function(range) {
  console.log('Now showing items ' + range.start + ' to ' + range.end);
}

onRender(startIndex, endIndex)

Fires after every DOM update, immediately after new items are written to the page.

onRender: function(startIndex, endIndex) {
  console.log('DOM updated: items ' + startIndex + ' to ' + endIndex);
}

onReachEnd({ start, end, total }) / onLoadMore (alias)

Fires once when the user scrolls near the bottom of the list. Resets automatically when the user scrolls back up past the threshold. Use for infinite loading. The alias onLoadMore works identically.

onReachEnd: function(info) {
  fetchNextPage(info.total).then(function(batch) {
    vs.append(batch);
  });
}

onReachStart({ start, end, total })

Fires once when the user scrolls near the top of the list. Use for loading older history in reverse-mode (chat) lists.

onReachStart: function(info) {
  loadHistory().then(function(older) {
    vs.prepend(older);
  });
}

onResize({ width, height })

Fires when the container element is resized (powered by ResizeObserver). The list re-renders automatically - this callback is for your own side effects.

onResize: function(size) {
  console.log('Container is now ' + size.width + ' x ' + size.height + ' px');
}

Data

Scroll