@voltilt/z-timeline

Virtualized Z-axis scroll timeline — thousands of cards, flat DOM memory. Vanilla JS + CSS 3D.

Install

npm install @voltilt/z-timeline

import { createZTimeline, createArraySource } from '@voltilt/z-timeline';
import '@voltilt/z-timeline/style.css';

CDN (jsDelivr)

Package page · pin a version in production:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@voltilt/[email protected]/src/style.css" />
<script type="module">
  import { createZTimeline, createArraySource } from 'https://cdn.jsdelivr.net/npm/@voltilt/[email protected]/+esm';
</script>

Markup

<div class="vt-z-root">
  <div class="vt-z-scroll-proxy" data-vt-scroll-proxy></div>
  <div class="vt-z-viewport" data-vt-viewport>
    <div class="vt-z-scene-wrapper" data-vt-scene-wrapper>
      <div class="vt-z-scene" data-vt-scene></div>
    </div>
    <div class="vt-z-empty vt-hidden" data-vt-empty><p>No items</p></div>
  </div>
</div>

The scroll-proxy must live in document flow (not inside the fixed viewport) so window scroll height drives the camera.

API

const source = createArraySource(items); // or your own getTotal / fetchPage

const timeline = createZTimeline({
  root: document.querySelector('.vt-z-root'),
  getTotal: source.getTotal,
  fetchPage: source.fetchPage,
  renderItem(item, index) {
    const el = document.createElement('article');
    el.innerHTML = `<div class="vt-z-card-content"><h2>${item.title}</h2></div>`;
    return el;
  },
  onFocusChange(index, item) { /* … */ },
});

timeline.bind();
await timeline.refresh();
timeline.jumpToIndex(100);
timeline.destroy();

Items need a stable id (or pass itemId).

License

MIT · KohlerCode