Virtual

Zero-dependency virtual scrolling Web Component.

npm install @blueprintui/virtual
GitHub StackblitzNPM

Basic Usage

Render thousands of items with only the visible ones in the DOM. The component emits bp-virtual-change events when the visible range changes, allowing you to render only what's needed.

<bp-virtual-list
  id="demo-list"
  height="300px"
  item-height="44"
  item-count="10000"></bp-virtual-list>
import 'https://cdn.jsdelivr.net/npm/@blueprintui/[email protected]/include/virtual-list.js/+esm';

const list = document.querySelector('bp-virtual-list');
const data = Array.from({ length: 10000 }, (_, i) => ({ id: i, name: 'Item ' + i }));

list.addEventListener('bp-virtual-change', event => {
  list.innerHTML = data.slice(event.detail.start, event.detail.end)
    .map(item => '<div>' + item.name + '</div>')
    .join('');
});

Commands

Control scroll position with HTML invoker commands.

<button commandfor="demo-command" command="--scroll-to-index" value="500">Scroll to 500</button>
<button commandfor="demo-command" command="--scroll-to-index" value="0">Scroll to First</button>
<button commandfor="demo-command" command="--scroll-to-index" value="10000">Scroll to Last</button>

<bp-virtual-list id="demo-command" height="250px" item-height="44" item-count="10000"></bp-virtual-list>
Scroll to 500Scroll to FirstScroll to Last

Scroll Events

The bp-virtual-scroll event provides scroll position and direction, useful for implementing infinite scroll or scroll-based UI updates.

list.addEventListener('bp-virtual-scroll', ({ detail }) => {
  console.log('Position:', detail.scrollTop);
  console.log('Direction:', detail.direction); // 'up', 'down', or 'idle'
});
Scroll position: 0, Direction: idle

Scroll To Index

Use the scrollToIndex() method to programmatically scroll to any item in the list. Supports both instant and smooth scrolling.

// Instant jump to item 500
list.scrollToIndex(500);

// Smooth scroll to item 500
list.scrollToIndex(500, 'smooth');

// Back to top
list.scrollToIndex(0, 'smooth');
Jump to 500Smooth to 500Back to top

API

Properties / Attributes

PropertyAttributeTypeDefaultDescription
itemHeightitem-heightnumber44Fixed height per item in pixels
itemCountitem-countnumber0Total items in dataset
itemBufferitem-buffernumber1Buffer items outside viewport
heightheightstring'auto'Container height (CSS value)

Events

EventDetailDescription
bp-virtual-change{ start, end, count }Visible range updated
bp-virtual-scroll{ scrollTop, direction }Scroll position changed

Commands

CommandDescription
--scroll-to-indexScroll to item at index based on the value of the source button issuing the command

Methods

MethodSignatureDescription
scrollToIndex(index, behavior?) => voidScroll to item at index
refresh() => voidForce recalculation of visible range

CSS Custom Properties

PropertyDefaultDescription
--heightautoContainer height
--width100%Container width
--scrollbar-widthautoScrollbar width
--scrollbar-colorautoScrollbar color