DScroll

A slim, fast, vanilla-JS virtual-scrolling library for fixed-height row lists. Zero dependencies. Plugin-extensible. Real DOM-node recycling pool.

Author: Dharmesh Patel · License: MIT · Version: 1.2.0

DScroll renders only the rows currently visible in a scroll container, plus a small buffer ahead and behind. It's intentionally narrow: fixed-height rows, single-axis (vertical), no framework adapters. Variable heights, multi-column layouts, etc. land later as plugins or in V2.

What makes DScroll different

• Real DOM-node recycling pool — most vanilla peers destroy + recreate row nodes on every range crossing. DScroll keeps a fixed pool and rebinds existing nodes, paying zero appendChild/removeChild cost during scroll.
• Direction-biased buffer with velocity-aware scaling and inertia projection — most peers use a fixed symmetric overscan. DScroll renders more rows ahead of motion direction, scales the buffer with scroll velocity, and projects 4 frames forward under inertia (mitigates iOS Safari's blank-on-momentum issue).
• Plugin architecture where every V2+ feature lands as a plugin without touching core (extend() + scheduleAfter() primitives).
• Zero allocations in the hot scroll path (steady state).
• ~605 LOC core across dmath.js + dpool.js + dscroll.js.

Where it's used

DScroll powers the project task panel virtualization in DPlan, where it scrolls many-thousand-task plans on desktop trackpads at 60 fps with a fixed pool of ~225 row nodes.

This package is the standalone extraction of that library — same code, same contract, available for any project that needs vanilla virtual scrolling.

Install

npm install dscroll

Or drop the folder in directly (no build required):

cp -r path/to/dscroll/ ./vendor/dscroll

import DScroll from 'dscroll';
// Or with the vendor copy:
import DScroll from './vendor/dscroll/dscroll.js';

For TypeScript users, declarations ship as dscroll.d.ts alongside.

Quick start

<div id="my-list-scroll" style="height: 600px; overflow-y: auto">
  <div id="my-list-rows" style="position: relative"></div>
</div>

<script type="module">
  import DScroll from 'dscroll';

  const data = [/* …5000 task objects… */];

  const ds = DScroll.create({
    scrollContainer: '#my-list-scroll',
    rowContainer:    '#my-list-rows',
    rowHeight:       28,
    renderRow(node, task, ctx) {
      // Mutate node in place. Called when node binds to new data.
      node.dataset.id   = task.id;
      node.textContent  = task.name;
      node.className    = 'row' + (task.urgent ? ' urgent' : '');
    },
  });

  ds.setData(data);
</script>

That's it. The library handles the rest.

Public API

Creation

DScroll.create(options) → instance

| Option | Type | Required | Description | |---|---|---|---| | scrollContainer | string \| Element | ✓ | Element with overflow-y: scroll. CSS selector or DOM node. | | rowContainer | string \| Element | ✓ | Element inside scrollContainer that holds rows. Must be position: relative. | | rowHeight | number | ✓ | Pixel height of every row. Fixed; does not vary. | | renderRow | (node, data, ctx) => void | ✓ | Mutate node in place when it binds to data. | | poolSize | number | optional | Auto-computed from viewport + buffer. Override for predictable memory. | | buffer | { fwd, back, base } | optional | Default { 250, 30, 75 }. Smaller for memory-constrained scenarios. | | plugins | Plugin[] | optional | Plugin instances; see Plugins below. | | devMode | boolean | optional | Asserts invariants on every operation; throws on contract violation. | | onError | (err, ctx) => void | optional | Error handler for plugin/render errors. |

Instance methods (Stable since 1.0)

instance.setData(data)              // replace underlying data; preserves scroll
instance.invalidate(dataId)         // re-render a single row (O(1))
instance.scrollToIndex(idx, { align, behavior })
instance.destroy()                  // teardown; idempotent
instance.on(event, handler) → unsubscribe
instance.off(event, handler)
instance.isScrolling()              // boolean
instance.getRange() → { start, end }
instance.getPool()                  // beta — read-only pool view

Instance methods (Stable since 1.2)

instance.extend(namespace, methods)          // sanctioned plugin namespace channel
instance.scheduleAfter(ms, fn) → handle      // destroy-coordinated setTimeout

See API.md for full signatures, complexity, and stability guarantees.

Events

| Event | Payload | When fired | |---|---|---| | init | { instance } | After create() returns | | bind | { node, data, ctx } | A pool node was bound to new data | | unbind | { node } | A pool node was released | | scroll | { scrollTop, direction, velocity, isScrolling } | After scroll handler processes an event | | range | { start, end, prevStart, prevEnd } | Visible range changed | | resize | { width, height } | Container resized | | render | { count, durationMs } | Render cycle completed | | destroy | {} | Before instance teardown |

Plugins

Plugins are how V2+ features land without modifying core. A plugin is a function returning a hook object:

function MyPlugin(opts = {}) {
  return {
    name: 'my-plugin',
    onInit(instance)         { /* setup; call instance.extend('myns', {...}) here */ },
    onBind(node, data, ctx)  { /* row got new data */ },
    onUnbind(node)           { /* row released */ },
    onScroll(state)          { /* scrolled */ },
    onResize(state)          { /* viewport resized */ },
    onRender(range)          { /* visible range changed */ },
    onDestroy()              { /* teardown — timers via scheduleAfter auto-cancel */ },
  };
}

All hooks optional. Pass via plugins option.

Built-in plugins

| Plugin | Status | Purpose | |---|---|---| | flash | V1.2 shipped | Pool-aware row flash. Reference plugin shape. See plugins/flash/. | | scrollRestore | V1.3 planned | Persist + restore scroll position via localStorage. | | keyboardNav | V1.3 planned | Arrow-key navigation between rows. | | stickyGroups | V2.0 planned | Sticky group headers. | | animation | V2.0 planned | Row insert / remove / move animations. |

Plugin contract guarantees:

1. Hooks called in registration order.
2. Errors caught — one plugin's bug never breaks another or core.
3. extend() is the only sanctioned channel for namespace mutation; scheduleAfter() is the only sanctioned channel for plugin timers (auto-cancelled in destroy()).
4. Plugins observe — they don't intercept.

Full contract in ARCHITECTURE.md §4.2.

Performance & capacity

Tested operating envelope (Chrome 147 / macOS Intel, 5× median):

| Tier | Rows | Cold render (typ.) | p99 frame (typ.) | Sustained scroll | |---|---|---|---|---| | Sweet spot | 0 – 10,000 | 14–17 ms | 17.6 ms | 60 fps | | Designed-for | 10k – 100,000 | 14–16 ms | 17.6 ms | 60 fps | | Stretch | 100k – 500,000 | 14–25 ms | 17.6–67 ms | 49–60 fps |

Hot-path contracts (asserted by Node bench in CI):

• Scroll handler ≤ 4 ms p99 at every tier
• Per-flash-call ≤ 0.05 ms p50 (when flash plugin is loaded)
• Heap delta ≤ 100 KB after 1000 scroll events

See BENCHMARKS.md for full head-to-head measurement against TanStack Virtual and virtua, including methodology and disclaimers.

Browser support

• Chrome / Edge: 90+
• Firefox: 88+
• Safari: 14+ (modern WebKit)
• Mobile Safari iOS: 14+
• Mobile Chrome Android: 90+

Requires native ES module import, ResizeObserver, requestAnimationFrame, and CSS transform: translate3d. No polyfills shipped.

Documents in this folder

| File | Purpose | |---|---| | README.md (this) | Quickstart + API surface | | ARCHITECTURE.md | Design rationale, SOLID mapping, plugin contract | | API.md | Function-level registry (every public + internal fn) | | CONTRACTS.md | Invariants + capacity envelope | | CHANGELOG.md | Version history (Keep-a-Changelog format) | | BENCHMARKS.md | Performance baselines + head-to-head with peers | | PRIOR_ART.md | Library research + failure modes inherited from peers | | FUTURE_IDEAS.md | Backlog of deferred features with triggers | | DscrollFlash.md | V1.2 flash plugin spec (Round Table locked) | | LICENSE | MIT | | NOTICE.md | Third-party notices (none for runtime; peer benches only) |

Running tests + benchmarks

npm test                                # 301 tests across 5 files
npm run bench                           # Node-based flash plugin perf gates

# Browser-based benches (require local HTTP server, not file://)
python3 -m http.server 8080
# open http://localhost:8080/bench/peers.html        # 5-library × 5-tier head-to-head
# open http://localhost:8080/bench/run.html          # capacity sweep
# open http://localhost:8080/bench/v1-vs-v2.html     # row-renderer micro-bench
# open http://localhost:8080/stress.html             # interactive stress test

Contributing

PRs welcome. Every change must:

1. Add a CHANGELOG.md entry.
2. Update API.md if public surface changes.
3. Pass npm test (all 301 tests).
4. Not regress npm run bench (5 perf gates).

Public-API changes require a deprecation period. Internal API (_prefix) changes free.

License

MIT. Copyright (c) 2026 Dharmesh Patel. See LICENSE.