VirtualList

Renders large data lists into the viewport window: only visible items (plus a top/bottom buffer) are rendered, with head/tail padding placeholders to support the scroll height, and scroll events throttled via rAF. It is a generic rendering primitive reused by table / tree.

Basic Usage

Fixed-height virtual list

Example

Provide data via the items property (or the items attribute as a JSON string); height sets the viewport height and item-height the height of each item. Without a template, each item renders String(item) by default.

Custom Item Content

oas-item event-bound content

Example

Each visible item emits oas-item after rendering with detail containing { index, item, element }, which the host can use to fill in the item content; alternatively, a <template slot="item"> inside the component can serve as a static per-item template.

Scroll Events

oas-scroll window display

Visible window: 0–0 · scrollTop: 0

Example

Scroll events are emitted as oas-scroll, throttled by rAF, with detail being { scrollTop, start, end }.

Render Buffer

buffer controls how many extra items are pre-rendered above and below the visible area (default 4): a larger buffer means fewer blank areas (white screens) while scrolling, at the cost of more rendered DOM nodes.

Render buffer buffer

buffer="0": rendered items —; only items within the visible window are rendered.

buffer="8": rendered items —; 8 extra items pre-rendered above and below.

Example

Custom Scroll Container

scroll-target external container

Example

When scroll-target (a CSS selector) is set, the component does not provide its own scrollbar; instead an external container scrolls the whole content (e.g. page-level scrolling), and the window is computed from the external container's scrollTop.

API

Attributes

Attribute	Description	Type	Default
buffer	Number of items pre-rendered above/below (rendered early beyond the visible area to reduce scrolling blanks)	string	4
height	Viewport height (px)	string	320
item-height	Fixed height of each item (px)	string	36
items	Data array (property channel, takes precedence over the items attribute); data JSON string (attribute channel)	unknown[]	[]
scroll-target	CSS selector of the external scroll container; when set, the component has no scrollbar of its own and listens to the external scroll	string	—

Events

Event	Description
oas-item	Emitted after each visible item renders, detail: { index, item, element }
oas-scroll	Scroll event (rAF throttled), detail: { scrollTop, start, end }

Slots

Name	Description
template[slot="item"]	Static per-item template, cloned into each visible item container (optional)

Parts: ::part(viewport) scroll viewport, ::part(inner) content, ::part(padding-top) / ::part(padding-bottom) placeholders, ::part(item) a single item.