TanStack
Virtual

Marko Example: Ssr Restore
GitHub StackBlitz CodeSandbox

import { fetchPeople } from "../data"

// Jump target: render the window around item 100. Row height is 48px, so the scroll
// offset for item 100 is 100 * 48. `initialOffset` makes the server paint the slice at
// this position; the client restores the scroll to the same offset on mount so the
// server-rendered rows line up instead of the list snapping back to the top.
static const JUMP_INDEX = 100
static const ROW_HEIGHT = 48
static const JUMP_OFFSET = JUMP_INDEX * ROW_HEIGHT

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <title>SSR scroll restore (initialOffset) — @tanstack/marko-virtual</title>
    <style>
      * { box-sizing: border-box; margin: 0; padding: 0; }
      body { font-family: system-ui, sans-serif; padding: 24px; }
      h1 { font-size: 24px; margin-bottom: 8px; }
      p { color: #555; margin-bottom: 16px; max-width: 72ch; }
      code { background: #f3f4f6; padding: 1px 5px; border-radius: 4px; font-size: 12px; }
      .scroll-container { height: 400px; overflow-y: auto; border: 1px solid #e5e7eb; border-radius: 6px; position: relative; }
      .item { display: flex; align-items: center; gap: 16px; padding: 0 12px; font-size: 13px; border-bottom: 1px solid #f3f4f6; }
      .item-even { background: #f9fafb; }
      .item-odd  { background: #ffffff; }
      .idx   { width: 56px; color: #9ca3af; font-family: monospace; font-size: 12px; }
      .name  { width: 120px; font-weight: 600; }
      .email { flex: 1; color: #4b5563; font-family: monospace; font-size: 12px; }
      .role  { width: 90px; color: #6b7280; }
      .err   { color: #b91c1c; }
    </style>
  </head>
  <body>
    <h1>SSR scroll restore — <code>initialOffset</code></h1>
    <p>
      This list is server-rendered scrolled to item ${JUMP_INDEX} (e.g. a deep link or a restored
      scroll position). <code>initialOffset</code> tells the server to paint the slice around that
      offset instead of the top — view source and the first rows in the HTML are ~#${JUMP_INDEX + 1},
      not #1. On mount the client restores the scroll to the same offset so the rows stay put. Scroll
      up/down to re-window as usual.
    </p>

    <try>
      <@placeholder>
        <p>Loading people…</p>
      </@placeholder>
      <@catch|err|>
        <p class="err">Failed to load: ${(err as Error).message}</p>
      </@catch>

      <await|people| value=fetchPeople()>
        <div/scrollEl class="scroll-container">
          <virtualizer/v
            count=people.length
            estimateSize=() => ROW_HEIGHT
            getScrollElement=() => scrollEl()
            initialRect=({ width: 800, height: 400 })
            initialOffset=JUMP_OFFSET
          />
          <div style=`height: ${v.totalSize}px; width: 100%; position: relative`>
            <for|item| of=v.virtualItems>
              <const/person=people[item.index]/>
              <div
                class=item.index % 2 === 0 ? "item item-even" : "item item-odd"
                style=`position: absolute; top: 0; left: 0; width: 100%; height: ${item.size}px; transform: translateY(${item.start}px)`
              >
                <span class="idx">#${person!.id}</span>
                <span class="name">${person!.name}</span>
                <span class="email">${person!.email}</span>
                <span class="role">${person!.role}</span>
              </div>
            </for>
          </div>
        </div>

        <lifecycle onMount() {
          const el = scrollEl()
          if (el) el.scrollTop = JUMP_OFFSET
        }/>
      </await>
    </try>
  </body>
</html>