/ Examples
asyncscalescrollbarsnapshotsselection

Velocity-Based Loading

Pure vanilla JavaScript. Smart data loading that skips fetching when scrolling fast (>15 px/ms) and loads immediately when velocity drops. Handling 1,000,000 items with adaptive loading.

Items

0% 0.00 / 0.00 px/ms 0 / 0 items
0 requests 0 loaded
Source 
// Velocity-Based Loading - Pure Vanilla JavaScript
// Demonstrates smart loading that adapts to scroll velocity

import {
  vlist,
  withSelection,
  withAsync,
  withScale,
  withScrollbar,
  withSnapshots,
} from "vlist";
import {
  LOAD_VELOCITY_THRESHOLD,
  TOTAL_ITEMS,
  ITEM_HEIGHT,
  fetchItems,
  itemTemplate,
  setApiDelay,
  setUseRealApi,
  getUseRealApi,
  formatApiSource,
  formatVelocity,
  formatLoadedCount,
} from "../shared.js";
import { createStats } from "../../stats.js";
import { createInfoUpdater } from "../../info.js";

// Storage key for snapshots
const STORAGE_KEY = "vlist-velocity-loading-snapshot";

// Stats tracking
let loadRequests = 0;
let loadedCount = 0;
let currentVelocity = 0;
let isLoading = false;

// DOM references (will be set after DOM loads)
let loadRequestsEl, loadedCountEl;
let velocityValueEl, velocityFillEl, velocityStatusEl;

// Info bar right-side elements
let infoRequestsEl, infoLoadedEl;

let prevState = {
  loadRequests: -1,
  loadedCount: -1,
  isLoading: null,
  isAboveThreshold: null,
  velocityPercent: -1,
};

// Update panel controls (velocity display, sidebar stats)
function updateControls() {
  if (!velocityValueEl) return; // DOM not ready

  const velocityPercent = Math.min(100, (currentVelocity / 30) * 100);
  const isAboveThreshold = currentVelocity > LOAD_VELOCITY_THRESHOLD;

  if (prevState.loadRequests !== loadRequests) {
    loadRequestsEl.textContent = loadRequests;
    prevState.loadRequests = loadRequests;
  }

  if (prevState.loadedCount !== loadedCount) {
    loadedCountEl.textContent = formatLoadedCount(loadedCount);
    prevState.loadedCount = loadedCount;
  }

  if (prevState.isAboveThreshold !== isAboveThreshold) {
    if (isAboveThreshold) {
      velocityValueEl.parentElement.classList.add("velocity-display--fast");
      velocityFillEl.classList.add("velocity-bar__fill--fast");
      velocityFillEl.classList.remove("velocity-bar__fill--slow");
      velocityStatusEl.classList.add("velocity-status--skipped");
      velocityStatusEl.classList.remove("velocity-status--allowed");
      velocityStatusEl.textContent = "🚫 Loading skipped";
    } else {
      velocityValueEl.parentElement.classList.remove("velocity-display--fast");
      velocityFillEl.classList.remove("velocity-bar__fill--fast");
      velocityFillEl.classList.add("velocity-bar__fill--slow");
      velocityStatusEl.classList.remove("velocity-status--skipped");
      velocityStatusEl.classList.add("velocity-status--allowed");
      velocityStatusEl.textContent = "✅ Loading allowed";
    }
    prevState.isAboveThreshold = isAboveThreshold;
  }

  velocityValueEl.textContent = formatVelocity(currentVelocity);

  const roundedPercent = Math.round(velocityPercent);
  if (prevState.velocityPercent !== roundedPercent) {
    velocityFillEl.style.width = `${roundedPercent}%`;
    prevState.velocityPercent = roundedPercent;
  }
}

// Update footer right side (requests + loaded)
function updateContext() {
  if (infoRequestsEl) infoRequestsEl.textContent = loadRequests;
  if (infoLoadedEl) infoLoadedEl.textContent = formatLoadedCount(loadedCount);
}

// Build list — withSnapshots({ autoSave }) handles save/restore automatically.
// On first visit, autoLoad fetches data. On return visits, the snapshot provides
// the total and scroll position, and autoLoad is cancelled automatically.
const list = vlist({
  container: "#list-container",
  ariaLabel: "Virtual user list with velocity-based loading",
  item: {
    height: ITEM_HEIGHT,
    template: itemTemplate,
  },
})
  .use(withSelection({ mode: "single" }))
  .use(
    withAsync({
      adapter: {
        read: async ({ offset, limit }) => {
          loadRequests++;
          isLoading = true;
          updateControls();
          updateContext();
          const result = await fetchItems(offset, limit);
          isLoading = false;
          updateControls();
          updateContext();
          return result;
        },
      },
      storage: {
        chunkSize: 25,
      },
      loading: {
        cancelThreshold: LOAD_VELOCITY_THRESHOLD,
      },
    }),
  )
  .use(withScale())
  .use(withScrollbar({ autoHide: true }))
  .use(withSnapshots({ autoSave: STORAGE_KEY }))
  .build();

// =============================================================================
// Shared footer stats (left side — progress, velocity, items)
// =============================================================================

const stats = createStats({
  getScrollPosition: () => list?.getScrollPosition() ?? 0,
  getTotal: () => TOTAL_ITEMS,
  getItemSize: () => ITEM_HEIGHT,
  getContainerSize: () =>
    document.querySelector("#list-container")?.clientHeight ?? 0,
});

const updateInfo = createInfoUpdater(stats);

// Get DOM references
loadRequestsEl = document.getElementById("load-requests");
loadedCountEl = document.getElementById("loaded-count");
velocityValueEl = document.getElementById("velocity-value");
velocityFillEl = document.getElementById("velocity-fill");
velocityStatusEl = document.getElementById("velocity-status");

// Info bar right-side refs
infoRequestsEl = document.getElementById("info-requests");
infoLoadedEl = document.getElementById("info-loaded");

const btnSimulated = document.getElementById("btn-simulated");
const btnLiveApi = document.getElementById("btn-live-api");
const sliderDelay = document.getElementById("slider-delay");
const delayValueEl = document.getElementById("delay-value");
const btnStart = document.getElementById("btn-start");
const btnMiddle = document.getElementById("btn-middle");
const btnEnd = document.getElementById("btn-end");
const btnRandom = document.getElementById("btn-random");
const btnReload = document.getElementById("btn-reload");
const btnResetStats = document.getElementById("btn-reset-stats");

// Event bindings
list.on("scroll", () => {
  updateInfo();
});

list.on("range:change", () => {
  updateInfo();
});

list.on("velocity:change", ({ velocity }) => {
  currentVelocity = velocity;
  stats.onVelocity(velocity);
  updateInfo();
  updateControls();
});

list.on("load:start", () => {
  isLoading = true;
  updateControls();
  updateContext();
});

list.on("load:end", ({ items }) => {
  isLoading = false;
  loadedCount += items.length;
  updateControls();
  updateContext();
});

// Update button states
function updateDataSourceButtons() {
  const useRealApi = getUseRealApi();
  if (useRealApi) {
    btnSimulated.classList.remove("ui-segmented__btn--active");
    btnLiveApi.classList.add("ui-segmented__btn--active");
  } else {
    btnSimulated.classList.add("ui-segmented__btn--active");
    btnLiveApi.classList.remove("ui-segmented__btn--active");
  }
}

// Controls
btnSimulated.addEventListener("click", async () => {
  if (!getUseRealApi()) return; // Already simulated
  setUseRealApi(false);
  updateDataSourceButtons();
  loadedCount = 0;
  prevState.loadedCount = -1;
  updateControls();
  updateContext();
  await list.reload();
});

btnLiveApi.addEventListener("click", async () => {
  if (getUseRealApi()) return; // Already live
  setUseRealApi(true);
  updateDataSourceButtons();
  loadedCount = 0;
  prevState.loadedCount = -1;
  updateControls();
  updateContext();
  await list.reload();
});

sliderDelay.addEventListener("input", () => {
  const delay = parseInt(sliderDelay.value, 10);
  setApiDelay(delay);
  delayValueEl.textContent = `${delay}ms`;
});

btnStart.addEventListener("click", () => {
  list.scrollToIndex(0, {
    align: "start",
    behavior: "smooth",
  });
});

btnMiddle.addEventListener("click", () => {
  const middle = Math.floor(TOTAL_ITEMS / 2);
  list.scrollToIndex(middle, {
    align: "center",
    behavior: "smooth",
  });
});

btnEnd.addEventListener("click", () => {
  list.scrollToIndex(TOTAL_ITEMS - 1, {
    align: "end",
    behavior: "smooth",
  });
});

btnRandom.addEventListener("click", () => {
  const index = Math.floor(Math.random() * TOTAL_ITEMS);
  list.scrollToIndex(index, {
    align: "center",
    behavior: "smooth",
  });
});

btnReload.addEventListener("click", async () => {
  loadedCount = 0;
  prevState.loadedCount = -1;
  updateControls();
  updateContext();
  await list.reload();
});

btnResetStats.addEventListener("click", () => {
  loadRequests = 0;
  loadedCount = 0;
  prevState.loadRequests = -1;
  prevState.loadedCount = -1;
  updateControls();
  updateContext();
});

// Initial update
updateDataSourceButtons();
updateControls();
updateContext();
updateInfo();
<div class="container">
    <header>
        <h1>Velocity-Based Loading</h1>
        <p class="description">
            Pure vanilla JavaScript. Smart data loading that skips fetching when
            scrolling fast (&gt;15 px/ms) and loads immediately when velocity
            drops. Handling 1,000,000 items with adaptive loading.
        </p>
    </header>

    <div class="split-layout">
        <div class="split-main">
            <h2 class="sr-only">Items</h2>
            <div id="list-container"></div>
        </div>

        <aside class="split-panel">
            <!-- Loading Stats -->
            <section class="ui-section">
                <h3 class="ui-title">Loading Stats</h3>
                <div class="stats-grid">
                    <div class="ui-card ui-card--compact stat-card">
                        <div id="load-requests" class="stat-card__value">0</div>
                        <div class="stat-card__label">Requests</div>
                    </div>
                    <div class="ui-card ui-card--compact stat-card">
                        <div id="loaded-count" class="stat-card__value">0</div>
                        <div class="stat-card__label">Loaded</div>
                    </div>
                </div>
            </section>

            <!-- Velocity Display -->
            <section class="ui-section">
                <h3 class="ui-title">Scroll Velocity</h3>
                <div class="ui-card ui-card--compact velocity-display">
                    <span id="velocity-value" class="velocity-display__value"
                        >0.0</span
                    >
                    <span class="velocity-display__unit">px/ms</span>
                </div>
                <div class="velocity-bar">
                    <div id="velocity-fill" class="velocity-bar__fill"></div>
                    <div class="velocity-bar__marker"></div>
                </div>
                <div class="velocity-labels">
                    <span class="velocity-labels__first">0</span>
                    <span class="velocity-labels__threshold">15</span>
                    <span class="velocity-labels__last">30+</span>
                </div>
                <div
                    id="velocity-status"
                    class="velocity-status velocity-status--allowed"
                >
                    ✅ Loading allowed
                </div>
            </section>

            <!-- Data Source -->
            <section class="ui-section">
                <h3 class="ui-title">Data Source</h3>
                <div class="ui-segmented">
                    <button id="btn-simulated" class="ui-segmented__btn">
                        🧪 Simulated
                    </button>
                    <button
                        id="btn-live-api"
                        class="ui-segmented__btn ui-segmented__btn--active"
                    >
                        ⚡ Live API
                    </button>
                </div>
            </section>

            <!-- API Delay -->
            <section class="ui-section">
                <div class="ui-row">
                    <label class="ui-label" for="slider-delay">
                        API Delay
                        <span id="delay-value" class="ui-value">0ms</span>
                    </label>
                    <input
                        id="slider-delay"
                        type="range"
                        class="ui-slider"
                        min="0"
                        max="1000"
                        step="20"
                        value="0"
                    />
                </div>
            </section>

            <!-- Navigation -->
            <section class="ui-section">
                <h3 class="ui-title">Navigation</h3>
                <div class="ui-row">
                    <div class="ui-btn-group">
                        <button
                            id="btn-start"
                            class="ui-btn ui-btn--icon"
                            title="First item"
                        >
                            <i class="icon icon--up"></i>
                        </button>
                        <button
                            id="btn-middle"
                            class="ui-btn ui-btn--icon"
                            title="Middle"
                        >
                            <i class="icon icon--center"></i>
                        </button>
                        <button
                            id="btn-end"
                            class="ui-btn ui-btn--icon"
                            title="Last item"
                        >
                            <i class="icon icon--down"></i>
                        </button>
                        <button
                            id="btn-random"
                            class="ui-btn ui-btn--icon"
                            title="Random item"
                        >
                            <i class="icon icon--shuffle"></i>
                        </button>
                    </div>
                </div>
            </section>

            <!-- Actions -->
            <section class="ui-section">
                <h3 class="ui-title">Actions</h3>
                <div class="ui-btn-group">
                    <button id="btn-reload" class="ui-btn">Reload</button>
                    <button id="btn-reset-stats" class="ui-btn">
                        Reset Stats
                    </button>
                </div>
            </section>
        </aside>
    </div>

    <div class="example-info" id="example-info">
        <div class="example-info__left">
            <span class="example-info__stat">
                <strong id="info-progress">0%</strong>
            </span>
            <span class="example-info__stat">
                <span id="info-velocity">0.00</span> /
                <strong id="info-velocity-avg">0.00</strong>
                <span class="example-info__unit">px/ms</span>
            </span>
            <span class="example-info__stat">
                <span id="info-dom">0</span> /
                <strong id="info-total">0</strong>
                <span class="example-info__unit">items</span>
            </span>
        </div>
        <div class="example-info__right">
            <span class="example-info__stat">
                <strong id="info-requests">0</strong>
                <span class="example-info__unit">requests</span>
            </span>
            <span class="example-info__stat">
                <strong id="info-loaded">0</strong>
                <span class="example-info__unit">loaded</span>
            </span>
        </div>
    </div>
</div>
// Shared data and utilities for velocity-loading example variants
// This file is imported by all framework implementations to avoid duplication

// =============================================================================
// Constants
// =============================================================================

export const LOAD_VELOCITY_THRESHOLD = 15; // px/ms
export const TOTAL_ITEMS = 1000000;
export const API_BASE =
  typeof location !== "undefined" ? location.origin : "http://localhost:3338";
export const ITEM_HEIGHT = 72;

// =============================================================================
// API State
// =============================================================================

let apiDelay = 0;
let useRealApi = true; // Start with live API by default

export const setApiDelay = (delay) => {
  apiDelay = delay;
};

export const setUseRealApi = (value) => {
  useRealApi = value;
};

export const getUseRealApi = () => useRealApi;

// =============================================================================
// Real API — fetches from vlist.io backend
// =============================================================================

const fetchFromApi = async (offset, limit) => {
  const params = new URLSearchParams({
    offset: String(offset),
    limit: String(limit),
    total: String(TOTAL_ITEMS),
  });
  if (apiDelay > 0) params.set("delay", String(apiDelay));

  const res = await fetch(`${API_BASE}/api/users?${params}`);
  if (!res.ok) throw new Error(`API error: ${res.status}`);
  return res.json();
};

// =============================================================================
// Simulated API — deterministic in-memory fallback
// =============================================================================

const generateItem = (id) => ({
  id,
  name: `User ${id}`,
  email: `user${id}@example.com`,
  role: ["Admin", "Editor", "Viewer"][id % 3],
  avatar: String.fromCharCode(65 + (id % 26)),
});

const fetchSimulated = async (offset, limit) => {
  if (apiDelay > 0) await new Promise((r) => setTimeout(r, apiDelay));
  const items = [];
  const end = Math.min(offset + limit, TOTAL_ITEMS);
  for (let i = offset; i < end; i++) items.push(generateItem(i + 1));
  return { items, total: TOTAL_ITEMS, hasMore: end < TOTAL_ITEMS };
};

// =============================================================================
// Unified fetch
// =============================================================================

export const fetchItems = (offset, limit) =>
  useRealApi ? fetchFromApi(offset, limit) : fetchSimulated(offset, limit);

// =============================================================================
// Template — single template for both real items and placeholders.
// The renderer adds .vlist-item--placeholder on the wrapper element,
// so CSS handles the visual difference (skeleton blocks, shimmer, etc).
// Placeholder items carry the same fields as real data, filled with
// mask characters (x) sized to match actual data from the first batch.
// =============================================================================

export const itemTemplate = (item, index) => {
  const displayName = item.firstName
    ? `${item.firstName} ${item.lastName}`
    : item.name || "";
  const avatarText = item.avatar || displayName[0] || "";

  return `
    <div class="item-content">
      <div class="item-avatar">${avatarText}</div>
      <div class="item-details">
        <div class="item-name">${displayName} (#${index + 1})</div>
        <div class="item-email">${item.email || ""}</div>
        <div class="item-role">${item.role || ""}</div>
      </div>
    </div>
  `;
};

// =============================================================================
// Utilities
// =============================================================================

export const formatApiSource = (useRealApi) =>
  useRealApi ? "⚡ Live API" : "🧪 Simulated";

export const formatVelocity = (velocity) => velocity.toFixed(1);

export const formatLoadedCount = (count) => count.toLocaleString();
/* Basic Example — example-specific styles only
   Common styles (.container, h1, .description, .stats, footer)
   are provided by example/example.css using shell.css design tokens.
   UI components (.split-layout, .split-panel, .ui-*)
   is also provided by example/example.css. */

/* List container height */
#list-container {
    height: 600px;
    max-width: 360px;
    margin: 0 auto;
}

/* ============================================================================
   Item styles (inside list)
   ============================================================================ */

.vlist-item {
    padding: 0 16px;
}

.item-content {
    display: flex;
    align-items: center;
    gap: 12px;
    padding: 0;
    height: 100%;
    width: 100%;
}

.item-avatar {
    width: 40px;
    height: 40px;
    border-radius: 50%;
    background: var(--accent);
    display: flex;
    align-items: center;
    justify-content: center;
    color: white;
    font-weight: 600;
    font-size: 16px;
    flex-shrink: 0;
}

.item-details {
    flex: 1;
    min-width: 0;
    display: flex;
    flex-direction: column;
    justify-content: center;
}

.item-name {
    font-weight: 500;
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
}

.item-email {
    font-size: 12px;
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
}

.item-role {
    font-size: 12px;
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
}

.item-index {
    font-size: 12px;
    min-width: 60px;
    text-align: right;
}

/* ============================================================================
   Placeholder skeleton — driven by .vlist-item--placeholder on the wrapper.
   The template is identical for real and placeholder items; mask characters
   (x) set the natural width, CSS hides them and shows skeleton blocks.
   ============================================================================ */

.vlist-item--placeholder .item-avatar {
    background-color: rgba(102, 126, 234, 0.9);
    color: transparent;
}

.vlist-item--placeholder .item-name {
    color: transparent;
    background-color: var(--vlist-placeholder-bg);
    border-radius: 4px;
    width: fit-content;
    min-width: 60%;
    line-height: 1.1;
    margin-bottom: 1px;
}

.vlist-item--placeholder .item-email {
    color: transparent;
    background-color: var(--vlist-placeholder-bg);
    border-radius: 4px;
    width: fit-content;
    min-width: 70%;
    line-height: 1;
    margin-bottom: 1px;
}

.vlist-item--placeholder .item-role {
    color: transparent;
    background-color: var(--vlist-placeholder-bg);
    border-radius: 4px;
    width: fit-content;
    min-width: 30%;
    line-height: 1;
}

/* ============================================================================
   Velocity-specific styles
   ============================================================================ */

.stats-grid {
    display: grid;
    grid-template-columns: repeat(2, 1fr);
    gap: 12px;
}

.stat-card {
    text-align: center;
    padding: 7px 9px;
}

.stat-card__value {
    font-size: 20px;
    font-weight: 700;
    color: var(--text);
}

.stat-card__value--loading {
    color: var(--accent);
}

.stat-card__value--idle {
    color: #43e97b;
}

.stat-card__label {
    font-size: 12px;
    color: var(--text-muted);
    text-transform: uppercase;
    letter-spacing: 0.5px;
}

.velocity-display {
    display: flex;
    align-items: baseline;
    justify-content: center;
    gap: 4px;
    margin-bottom: 4px;
    padding: 7px 9px;
}

.velocity-display--fast {
    background: color-mix(in srgb, #fa709a 10%, transparent);
    border-color: color-mix(in srgb, #fa709a 20%, var(--border));
}

.velocity-display__value {
    font-size: 24px;
    font-weight: 700;
    font-variant-numeric: tabular-nums;
}

.velocity-display__unit {
    font-size: 16px;
    color: var(--text-muted);
    font-weight: 500;
}

.velocity-bar {
    position: relative;
    height: 16px;
    background: var(--surface-container);
    border-radius: 8px;
    overflow: hidden;
    margin-bottom: 8px;
}

.velocity-bar__fill {
    height: 100%;
    background: linear-gradient(90deg, #43e97b, #667eea);
    transition:
        width 0.3s ease,
        background 0.2s ease;
    border-radius: 8px;
    width: 0%;
}

.velocity-bar__fill--fast {
    background: linear-gradient(90deg, #667eea, #fa709a);
}

.velocity-bar__fill--slow {
    background: linear-gradient(90deg, #43e97b, #667eea);
}

.velocity-bar__marker {
    position: absolute;
    left: 50%;
    top: 0;
    bottom: 0;
    width: 2px;
    background: var(--outline-variant, rgba(0, 0, 0, 0.3));
}

.velocity-labels {
    display: flex;
    justify-content: space-between;
    font-size: 11px;
    color: var(--text-muted);
    margin-bottom: 12px;
}

.velocity-labels .velocity-labels__first {
    flex: 1;
}

.velocity-labels .velocity-labels__threshold {
    flex: none;
    font-weight: 600;
}

.velocity-labels .velocity-labels__last {
    flex: 1;
    text-align: right;
}

.velocity-status {
    padding: 12px 16px;
    border-radius: 8px;
    text-align: center;
    font-weight: 600;
    font-size: 14px;
    transition: all 0.2s ease;
}

.velocity-status--allowed {
    background: color-mix(in srgb, #43e97b 10%, transparent);
    color: var(--color-success, #2ea563);
}

.velocity-status--skipped {
    background: color-mix(in srgb, #fa709a 10%, transparent);
    color: var(--color-error, #d63c6f);
}

/* ============================================================================
   Responsive
   ============================================================================ */

@media (max-width: 820px) {
    #list-container {
        max-width: none;
        height: 400px;
    }
}