Virtual Scroll

A list of any length that holds only the rows in view, rendered by the server.

zweiundeins <sb-virtual-scroll> virtual list infinite scroll windowing large data grid feed hyperlith Since 2026-09-29 MIT licence 3.3 kB0 Open in playground Edit on GitHub

Playground

Sirius
Canopus
Arcturus
Vega
Capella
Rigel
Procyon
Achernar
Betelgeuse
Hadar
Altair
Acrux

A scroll container for a list of any length. The server renders the items as plain HTML, and the page holds only the rows in view plus a buffer around them. The component does the geometry: it makes the scrollbar as long as the whole list, puts the items where they belong, and asks for a new window when you scroll far enough. This is Anders Murphy's approach in hyperlith.

The server owns offset, total and the items. The scroll position stays in the browser. There is no value to send back, so no command contract either.

Examples

A million rows from the server

A star catalog of 1,000,000 lines, which the server computes from each line's index (/demo/data/list). Drag the scrollbar anywhere: the rows arrive a moment later, and the bars stand in for rows that are on their way.

<style>
  #stars > div { display: flex; gap: 1.5ch; align-items: center; padding-inline: 0.75rem; font-size: 0.75rem; font-variant-numeric: tabular-nums; white-space: nowrap; overflow: hidden; }
  #stars b { color: var(--sb-text-1); }
</style>
<sb-virtual-scroll id="stars" label="Star catalog" item-size="17" data-ignore-morph
  data-on:sb-window="@get('/demo/data/list?id=stars&offset=' + evt.detail.offset + '&count=' + evt.detail.count)"></sb-virtual-scroll>
  1. On connect, and whenever the viewport passes half the buffer, the list emits sb-window with { offset, count }: the rows in view plus the buffer (4,000px of rows by default) above and below.
  2. @get asks the server for that window.
  3. The server answers with the host element: the new offset and total, and the items as its children. Datastar's morph patches it like any other markup.

data-ignore-morph keeps this page's own frames away from the list (see Server side).

Column headings and jumping to an item

The header slot stays at the top while the rows scroll under it, and scrolls sideways with them: these rows are wider than a phone, so the list scrolls both ways. scrollToIndex() jumps to any item and so asks for its window.

First Star 50,000 Last
<style>
  #catalog { block-size: 16rem; }
  #catalog > div { display: grid; grid-template-columns: 6.5rem 3.5rem 10rem 6rem 6rem 4rem; gap: 1rem; align-items: center; inline-size: max-content; min-inline-size: 100%; padding-inline: 0.75rem; font-size: 0.8125rem; font-variant-numeric: tabular-nums; }
  #catalog > [slot="header"] { block-size: 2rem; background: var(--sb-surface-card); border-block-end: 1px solid var(--sb-border); color: var(--sb-text-muted); font-size: 0.75rem; }
</style>
<div style="display: grid; gap: 12px; inline-size: 100%">
  <sb-virtual-scroll id="catalog" label="Star catalog" item-size="28" data-ignore-morph
    data-on:sb-window="@get('/demo/data/list?id=catalog&total=100000&header&offset=' + evt.detail.offset + '&count=' + evt.detail.count)">
    <div slot="header" aria-hidden="true"><span>Star</span> <span>Class</span> <span>Constellation</span> <span>Brightness</span> <span>Distance</span> <span>Planets</span></div>
  </sb-virtual-scroll>
  <div style="display: flex; gap: 8px">
    <sb-button size="sm" variant="outline" data-on:click="document.getElementById('catalog').scrollToIndex(0)">First</sb-button>
    <sb-button size="sm" variant="outline" data-on:click="document.getElementById('catalog').scrollToIndex(49999)">Star 50,000</sb-button>
    <sb-button size="sm" variant="outline" data-on:click="document.getElementById('catalog').scrollToIndex(99999, { block: 'end' })">Last</sb-button>
  </div>
</div>

The header is part of the host's markup, so the server sends it with every window (&header here). Without it, the morph would remove it.

A grid

columns lays the items out in rows of that many: here a million pixels of a nebula, 48 to a row. With many items per row, a smaller buffer keeps the windows small.

<style>
  #nebula { block-size: 16rem; }
  #nebula .p1 { background: color-mix(in oklch, var(--sb-brand) 20%, transparent); }
  #nebula .p2 { background: color-mix(in oklch, var(--sb-brand) 45%, transparent); }
  #nebula .p3 { background: color-mix(in oklch, var(--sb-brand) 75%, transparent); }
  #nebula .p4 { background: var(--sb-brand-light); }
  #nebula .p5 { background: var(--sb-text-1); }
</style>
<sb-virtual-scroll id="nebula" label="Nebula, one pixel per item" item-size="12" columns="48" buffer="240" data-ignore-morph
  data-on:sb-window="@get('/demo/data/list?id=nebula&kind=pixels&columns=48&offset=' + evt.detail.offset + '&count=' + evt.detail.count)"></sb-virtual-scroll>

A feed of unknown length

An activity log in the ARIA feed pattern: role="feed" on the host, one <article> per entry. Click an entry and press Page Down or Page Up: the focus moves to the next or the previous article, also to one whose window is still on its way. Ctrl+End and Ctrl+Home leave the feed. The server counts no further than the windows it reads, so it sends total="-1" until a window reaches the end: the scrollbar grows as you scroll, and stops at the 2,000th entry. Rows are 2.25rem high and follow the page's font size, and windows start and end at a multiple of 25 entries.

<style>
  #feed { block-size: 16rem; }
  #feed > article { display: flex; gap: 1.5ch; align-items: center; padding-inline: 0.75rem; font-size: 0.8125rem; font-variant-numeric: tabular-nums; white-space: nowrap; overflow: hidden; border-block-end: 1px solid var(--sb-border-subtle); }
  #feed > article:focus-visible { outline: 2px solid var(--sb-brand-light); outline-offset: -2px; }
  #feed b { color: var(--sb-text-1); }
</style>
<sb-virtual-scroll id="feed" role="feed" aria-label="Star log" item-size="2.25rem" step="25" data-ignore-morph
  data-on:sb-window="@get('/demo/data/list?id=feed&kind=feed&unknown&total=2000&offset=' + evt.detail.offset + '&count=' + evt.detail.count)"></sb-virtual-scroll>

Server side

The handler behind these examples is Go with the sse package of lith, Starbase's runtime; any Datastar SDK works the same way. PatchElements morphs the element with the id in the markup, and demoListItem renders a star's line or a pixel:

// demoListKeep are the host attributes the page sets. This endpoint serves any
// page, so it sends only offset, total and the items, and the morph keeps these
// as the page has them. data-ignore-morph keeps the page's own frames, which
// know nothing of the window, away from the list.
const demoListKeep = "item-size columns buffer step label role aria-label style class data-ignore-morph data-on:sb-window"

// demoList answers an sb-virtual-scroll's sb-window with ?count= items from
// ?offset= (at most 5000), patched into the host with the id ?id=. The list is
// the star catalog: its million stars, or the first ?total=. &header adds the
// column headings; &kind=pixels&columns=<n> sends pixels of a nebula n wide,
// &kind=feed articles that take the focus. With &unknown the total is -1 until
// a window reaches the end of the list.
func (s *Server) demoList(w http.ResponseWriter, r *http.Request) {
	q := r.URL.Query()
	id := q.Get("id")
	if !elementIDRe.MatchString(id) {
		http.Error(w, "id must be an element id", http.StatusBadRequest)
		return
	}
	total, _ := strconv.Atoi(q.Get("total"))
	if total <= 0 || total > demo.CatalogSize {
		total = demo.CatalogSize
	}
	offset, _ := strconv.Atoi(q.Get("offset"))
	count, _ := strconv.Atoi(q.Get("count"))
	offset = min(max(offset, 0), total)
	count = min(max(count, 0), 5000, total-offset)
	cols, tag, role := 0, "div", ` role="listitem"`
	if q.Get("kind") == "feed" {
		tag, role = "article", ` tabindex="-1"`
	}
	if q.Get("kind") == "pixels" {
		cols, _ = strconv.Atoi(q.Get("columns"))
		cols = max(cols, 1)
	}

	// A server that reads a window without counting the whole list learns the
	// total only at its end: until then it says -1, "more may follow".
	if q.Has("unknown") && offset+count < total {
		total = -1
	}

	// The whole host: the morph patches it like any other markup.
	var b strings.Builder
	fmt.Fprintf(&b, `<sb-virtual-scroll id="%s" offset="%d" total="%d" data-preserve-attr="%s">`, id, offset, total, demoListKeep)
	if q.Has("header") {
		b.WriteString(`<div slot="header" aria-hidden="true"><span>Star</span> <span>Class</span> <span>Constellation</span> <span>Brightness</span> <span>Distance</span> <span>Planets</span></div>`)
	}
	for i := offset; i < offset+count; i++ {
		// aria-posinset and aria-setsize: the item's place in the whole list.
		attrs, content := demoListItem(i, cols)
		fmt.Fprintf(&b, `<%s%s aria-posinset="%d" aria-setsize="%d"%s>%s</%[1]s>`, tag, role, i+1, total, attrs, content)
	}
	b.WriteString(`</sb-virtual-scroll>`)

	w.Header().Set("Access-Control-Allow-Origin", "*") // public; used from the playground sandbox
	if stream, err := sse.Open(w, r, sse.Options{}); err == nil {
		stream.CloseWith(sse.PatchElements([]byte(b.String())))
	}
}
  • A query that patches the host, like this one: it doesn't know the rest of the host's markup, so data-preserve-attr tells the morph to keep those attributes. This page re-renders as a whole on every change, from markup that knows nothing of the window, so its lists carry data-ignore-morph. The endpoint's own patches still apply: they don't carry the attribute.
  • A page that re-renders as a whole, like hyperlith's: the window is the tab's state. sb-window posts a command that stores offset and count, and the page renders the list with its window and everything else. Nothing to preserve or ignore then, and the first render comes with its first window.

Windows

  • What the component asks for: sb-window carries offset (the first item, a multiple of columns) and count (enough rows to fill the viewport and the buffer on both sides). It asks once on connect, again when the viewport passes half the buffer on either side, and after a resize that needs more or fewer rows. Never on every scroll event, one request at a time, and never the window it asked for last: the same request would bring the same answer.
  • What the server sends: the host with offset (the index of its first child, from 0), total and the items as its children, in order. It may send fewer items than asked for (a cap): the list then asks for windows that fit the cap, with the viewport in the middle, so the rows in view still come. An empty list is total="0" and asks for nothing; a host without total asks for its first window again, as on connect.
  • Steps: with step, a window starts at a multiple of step items (rounded down) and ends at one (rounded up), so it still covers the rows in view and the buffer. Two readers scrolled to about the same place then ask for the same window, and a server that renders per window (a view per window in lith) renders it once for both. With columns, windows round to a multiple of both. Rounding adds up to step minus one item on each side, so a window is up to 2 × (step − 1) items longer than the buffer alone asks for. With a cap, the buffer shrinks until the rounded window fits the cap: keep step well under half the cap, or the rows in view may not fit.
  • Unknown length: a server that doesn't know the length yet (it reads a window without counting the whole list) sends total="-1". The scrollbar then reaches one window past the furthest item the server has sent, and grows with every window, and sb-window asks past the known end. Once a window reaches the end, the server sends the real total with it (a window short of the request with total="-1" counts as a cap, not the end). The demo endpoint above does this with &unknown: it says -1 until the window holds the list's last item. Give the items aria-setsize="-1" while the total is unknown.
  • Items: every item is one row of item-size (or one cell of a row, with columns). item-size is a number of px or any CSS length: 2.25rem, calc(1lh + 1rem), var(--row-height). A length is measured in a hidden element in the list's shadow root and rounded to whole px, again whenever it changes (the page's font size, the custom property): the geometry follows, and the row at the top of the view stays there.
  • Keys: an item may carry a key, a data-key or an id, that stays with it when items move. Without keys the morph patches the items by position and the list holds its scroll position, so an item inserted before the window moves the reader down a row. With keys, the item in the top row of the view keeps its place after a morph that moves it (a feed whose newest entries come first), unless the list is at the top and idle, with neither the focus nor the pointer in it: then the new items show at the top. A new list (a filter) that still holds that item keeps it in place too. On an item with both, data-key is its key. data-key is the safe choice: an id makes the morph move the elements, and Datastar v1.0.4 crashes on moved elements that contain a Rocket component.
  • Placeholders: the rows outside the current window show bars until their window arrives. The list never shows an item the server hasn't sent.
  • Length: browsers cap how tall an element can be, Firefox at about 17.9 million px (Chrome and Safari at about 33.5 million). Keep rows × item-size under that: a million rows of 17px fit everywhere; for more, use columns.

Methods

scrollToIndex(index, { block }) scrolls to the item at index (from 0). block is 'start' (the default: the item at the top), 'end', or 'nearest' (only as far as needed to show it, for keyboard navigation). When the item is outside the current window, the scroll asks for its window.

The list's own actions are scroll, trackFocus, leaveFocus and keyFirst. Rocket looks up an @name() on the host, an item or the header among them first, so a component that renders the list must not give its own actions these names. Datastar's actions, such as @get and @post, are unaffected.

Styling

Style it from your page's CSS, without changing the component or importing anything into it. Custom properties, inherited properties and ::part() all reach into its shadow root.

  • Size: block-size is 20rem by default; set it on the element (the list needs a height of its own to scroll). It fills the width it is given. Rows are exactly item-size high, and columns share the width.
  • Items: they are your markup, styled by your page's CSS (#stars > div). Rows wider than the list make it scroll sideways.
  • Fonts: the component draws no text.
  • Colours: the placeholder bars are --sb-surface-hover; the focus ring is --sb-brand-light. The header has no background of its own: give your header element one, or rows show through it.
  • Parts: scroller (the scrolling box), header (the sticky header row) and window (the grid that holds the items). Your page's ::part() rules win over the component's own, without !important.
  • Motion: nothing animates, and jumps are instant. For smooth ones, set scroll-behavior: smooth on ::part(scroller) inside @media (prefers-reduced-motion: no-preference).
  • State: :state(loading) while a window is on its way (the list is aria-busy then).
<style>
  #styled { block-size: 12rem; border: 1px solid var(--sb-border); border-radius: var(--sb-radius); --sb-surface-hover: var(--sb-brand-subtle); }
  #styled > div { padding-inline: 1rem; align-content: center; border-block-end: 1px solid var(--sb-border-subtle); }
  #styled:state(loading)::part(scroller) { cursor: progress; }
</style>
<sb-virtual-scroll id="styled" label="Star catalog" item-size="36" data-ignore-morph
  data-on:sb-window="@get('/demo/data/list?id=styled&total=10000&offset=' + evt.detail.offset + '&count=' + evt.detail.count)"></sb-virtual-scroll>

Accessibility

  • Roles: the scroller is a list, named by label. The items are the server's markup, so the server renders their role: role="listitem", with aria-posinset (the position, from 1) and aria-setsize (the total), so screen readers know where an item sits in the whole list, not only in the window. The component never changes the items: a morph would strip a role it added, and it would override the role of an item that is a link or a button.
  • Other structures: a role on the host hands the semantics to the page, and the scroller drops its list role: a feed (role="feed" with role="article" items), or a grid (role="grid", rows with aria-rowindex). Name the host with aria-label then.
  • Keyboard: when no item has anything to focus, the scroller takes the focus itself, so the arrow keys, Page Up and Down, Home and End scroll it. Otherwise Tab goes to the items' links, buttons, fields and elements with a tabindex.
  • Feeds: with role="feed" on the host, the keys of the ARIA feed pattern work: Page Down and Page Up move the focus to the next and the previous article, from the article that has it, or from the one at the top of the view when the scroller has it. An article outside the window takes the focus once its window arrives; until then the focus stays where it was, and further presses count on from the article they asked for. Ctrl+End moves the focus to the first element after the feed that Tab stops at, Ctrl+Home to the last one before it. The articles are the server's: give them tabindex="-1" so they take the focus themselves (otherwise their first link or button does), and aria-posinset and aria-setsize (-1 while the total is unknown).
  • Busy: while a window is on its way the list is aria-busy="true", set through its ElementInternals, so a morph never strips it. An aria-busy attribute on the host wins over it (sb-data-table sets one while its rows load).
  • Focus across windows: the morph patches the items by position, so a window can fill the focused element with another item or remove it. With keys, the list puts the focus back on the same element of the item with the same key as soon as the window lands. Without keys, or once that item is gone, it puts it on the item that now has its index, a frame after the window or at once when Tab is pressed before that, without scrolling, and Tab and Shift+Tab walk the items one at a time across any number of windows. It finds the element by its place among the item's links, buttons, fields and elements with a tabindex, counting those in a component's open shadow root too (the box of an sb-checkbox); in a row with a tabindex of its own, the link in it keeps the focus, not the row. When the element at that place is missing, disabled or hidden, the nearest one before it takes the focus, or else the nearest one after it. A component control that drops its tabindex while disabled (the box of a disabled sb-checkbox) leaves the count, so the elements after it move up one place. A page that moves the focus itself, like sb-data-table with its roving cell, has done so by then.
  • A new list: when the server sends a list that ends before the focused item, its new last item takes the focus. An item with nothing that takes the focus, and an empty list, give it to the scroller, also when the morph left the focused element showing another item.
  • Focus outside the window: when the focused item scrolls out of the window, the scroller holds the focus (with tabindex="-1" while it does), and a window that brings the item back gives it the focus again. A window never takes the focus back from the rest of the page. With a role on the host, the scroller has neither a role nor a name (ARIA allows no name on an element without a role), so it is an unnamed focus stop inside the host's table, grid or feed.
  • Header: a control in the header slot takes the focus without scrolling the list, and a focused item under the header scrolls into view below it. Tab from the header goes to the first item of the window, which can be up to buffer px above the view.

Installation

Add Datastar with Rocket and the Starbase autoloader once per page, then use the tag: the autoloader imports each component the first time its tag appears, including tags a Datastar morph adds later. The Datastar here is v1.0.5 with Starbase's patches. The components also run on the official v1.0.4 and v1.0.5.

<script type="importmap">
  { "imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" } }
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/autoloader.js"></script>

<sb-virtual-scroll id="stars" label="Stars" item-size="32"
  data-on:sb-window="@get('/stars?offset=' + evt.detail.offset + '&count=' + evt.detail.count)"></sb-virtual-scroll>

No flash of undefined elements: put class="sb-cloak" on <html> and add .sb-cloak :not(:defined) { visibility: hidden } to your CSS. The autoloader removes the class once the page's components are defined.

Load just this component, pinned to this version: all its modules in one minified file with its integrity hash, so the browser refuses it if a single byte changes.

<script type="importmap">
  {
    "imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" },
    "integrity": {
      "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js": "sha384-AfXVdZ/qxhMEHK4Nz/pJT6jl9xm3HGMBLBtC9yRuU5A7AQtXHYC0x6ap034vDqBV"
    }
  }
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/virtual-scroll@1e89e0453b4e/virtual-scroll.bundle.min.js" integrity="sha384-t+XsA2ZFVGabfDck378RXANlxMScZHvkJzyJUCuLnEb4ibJ6+ynjJsPMdiRCF1CE"></script>

<sb-virtual-scroll id="stars" label="Stars" item-size="32"
  data-on:sb-window="@get('/stars?offset=' + evt.detail.offset + '&count=' + evt.detail.count)"></sb-virtual-scroll>

Or the minified module files (one file, which the browser requests as it finds their imports), each pinned in the import map:

<script type="importmap">
  {
    "imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" },
    "integrity": {
      "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js": "sha384-AfXVdZ/qxhMEHK4Nz/pJT6jl9xm3HGMBLBtC9yRuU5A7AQtXHYC0x6ap034vDqBV",
      "https://starbase.zweiundeins.gmbh/c/virtual-scroll@1e89e0453b4e/virtual-scroll.min.js": "sha384-sNWlpttwgOdpTFXmcv12dbwqp6ZFdiKmybY+vJP4ZnU1J06GYlXKC1KomT1IWUoI"
    }
  }
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/virtual-scroll@1e89e0453b4e/virtual-scroll.min.js" integrity="sha384-sNWlpttwgOdpTFXmcv12dbwqp6ZFdiKmybY+vJP4ZnU1J06GYlXKC1KomT1IWUoI"></script>

<sb-virtual-scroll id="stars" label="Stars" item-size="32"
  data-on:sb-window="@get('/stars?offset=' + evt.detail.offset + '&count=' + evt.detail.count)"></sb-virtual-scroll>

In production, pin today's whole catalog: its autoloader and an import map with integrity hashes, so the browser refuses any file that changed. This map covers Datastar and this component; importmap.json has the hashes of every component, to merge into yours.

<script type="importmap">
  {
    "imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" },
    "integrity": {
      "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js": "sha384-AfXVdZ/qxhMEHK4Nz/pJT6jl9xm3HGMBLBtC9yRuU5A7AQtXHYC0x6ap034vDqBV",
      "https://starbase.zweiundeins.gmbh/c/virtual-scroll@1e89e0453b4e/virtual-scroll.bundle.min.js": "sha384-t+XsA2ZFVGabfDck378RXANlxMScZHvkJzyJUCuLnEb4ibJ6+ynjJsPMdiRCF1CE"
    }
  }
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/@81f24b268adb/autoloader.js" integrity="sha384-bWIhsIq9SpNUiIZyG/lv190MgHA05m8BVYA3LyIoE/pgOF3NUt0437e++4Ht1NcS"></script>

<sb-virtual-scroll id="stars" label="Stars" item-size="32"
  data-on:sb-window="@get('/stars?offset=' + evt.detail.offset + '&count=' + evt.detail.count)"></sb-virtual-scroll>

Components import only datastar and their own files, so copying is enough: save each component's one file (and a file it loads on first use, keeping its folder), and point the import map at your own copy of datastar-rocket.js (the /js/ paths stand for yours).

  • <sb-virtual-scroll>
    • virtual-scroll.bundle.min.js one file 3.3 kB brotli
<script type="importmap">
  { "imports": { "datastar": "/js/datastar-rocket.js" } }
</script>
<script type="module" src="/js/virtual-scroll/virtual-scroll.bundle.min.js"></script>

<sb-virtual-scroll id="stars" label="Stars" item-size="32"
  data-on:sb-window="@get('/stars?offset=' + evt.detail.offset + '&count=' + evt.detail.count)"></sb-virtual-scroll>

Or copy the module files, keeping each component's folder, and load each component's module:

  • <sb-virtual-scroll>
<script type="importmap">
  { "imports": { "datastar": "/js/datastar-rocket.js" } }
</script>
<script type="module" src="/js/virtual-scroll/virtual-scroll.min.js"></script>

<sb-virtual-scroll id="stars" label="Stars" item-size="32"
  data-on:sb-window="@get('/stars?offset=' + evt.detail.offset + '&count=' + evt.detail.count)"></sb-virtual-scroll>

In Go, render it with its typed templ wrapper: one field per prop, generated from the component's manifest (the module's README has the type rules). Add the module:

go get github.com/zweiundeins/starbase/templ@latest

Then load it, pinned with integrity hashes to the versions the module was generated with, and use it:

// In <head>: the components you list, pinned,
@sb.Imports(sb.ImportsProps{Components: []sb.Tag{sb.TagVirtualScroll}})
// or the autoloader, which also loads tags a morph adds later: @sb.Imports(sb.ImportsProps{})
// or, around the content of <body>, the components it renders: @sb.Tracked(sb.ImportsProps{}) { … }

@sb.VirtualScroll(sb.VirtualScrollProps{
	ID:       "stars",
	Label:    "Stars",
	ItemSize: "32",
	Attrs:    templ.Attributes{"data-on:sb-window": "@get('/stars?offset=' + evt.detail.offset + '&count=' + evt.detail.count)"},
})

Size

A page loads this component as one file, its bundle, compressed the way it is served (gzip -9, brotli -11): brotli is what it downloads. Datastar and Rocket are shared by every component and not counted.

FileOriginalgzipbrotli
virtual-scroll.bundle.min.js 7.9 kB3.6 kB3.3 kB
As module files: one request, 3.2 kB minified with brotli

For a page that loads the module files as they are, requesting each one as it finds its import, or bundles them itself. Each file compressed on its own; the minified one is what the page downloads, and the readable source is always there too.

FileOriginalgzipbrotliminified
virtual-scroll.js 21.9 kB7.2 kB6.3 kB3.2 kB

API reference

Props

AttributeTypeDefaultDescription
totalnumber0Server data: how many items the whole list has, or -1 while the server does not know (more may follow).
offsetnumber0Server data: the index of the first child in the whole list (from 0, a multiple of columns).
item-sizestring"32"Row height: a number of px, or a CSS length (2.5rem, calc(1lh + 1rem), var(--row)) measured in whole px. Every item is exactly one row high.
columnsnumber1Items per row: more than 1 lays them out as a grid.
buffernumber4000How far a window reaches past the viewport, above and below, in px.
stepnumber1Windows start and end at a multiple of step items, so viewers ask for the same windows (1: no rounding).
labelstring""Accessible name of the list.

Slots

NameDescription
defaultThe items of the current window, one element each, in order. The server renders them.
headerStays at the top while the items scroll under it, and scrolls sideways with them (column headings).

Events

NameDescription
sb-windowAsks for a window of items. detail: { offset, count }. Answer by re-rendering the host with those items as children and the new offset and total.