VirtualScroll

Data Display
stable

Window-based virtual list renderer that only mounts visible rows, keeping the DOM small for arbitrarily large datasets. Supports both wrapper and renderless modes.

Preview

Rendering the live preview…

wrapper

Rendering the live preview…

fixed height

Rendering the live preview…

renderless

Structure

Anatomy

Visual breakdown of the component's internal structure with BEM class call-outs.

Anatomy of OrigamVirtualScrollSchematic showing the virtual scroll container with spacers and visible items. spacer-top (padding-top) virtual-scroll-item #47 virtual-scroll-item #48 virtual-scroll-item #49 spacer-bottom (padding-bottom) 1 2 3
Anatomy of <origam-virtual-scroll> — the container ① holds a top spacer ② (padding-top), the currently visible VirtualScrollItems, and a bottom spacer ③ (padding-bottom). Items outside the viewport are unmounted.
1.origam-virtual-scroll
Scroll container. overflow-y: auto, height fixed or max-height constrained.
2.origam-virtual-scroll__spacer
Top spacer div. padding-top dynamically set to fill the height of all items above the visible window.
3.origam-virtual-scroll__spacer (bottom)
Bottom spacer div. padding-bottom fills the height of all items below the visible window.

API

Props

All props accepted by this component, with their type, default value and description.

items
Array<any>
[]
Source array of items to virtualize. Can contain any value — the type is forwarded as-is to the #default slot.
renderless
boolean
false
When true, removes the scroll container wrapper — the parent is responsible for the scroll context. Useful when embedding inside a Dialog or custom scroll root.
id
string
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue
overscan
number
2
Number of items rendered outside the visible window for smooth scrolling. Higher values reduce blank flashes but increase DOM size.
height
number | string
Height of the scroll container. Required unless renderless=true.
maxHeight
number | string
Maximum height for the container (used with auto-height layouts).
maxWidth
number | string
minHeight
number | string
minWidth
number | string
width
number | string
itemHeight
number | string
null
Estimated (or fixed) item height in pixels. Used for initial spacer calculation. When null, item heights are measured dynamically via ResizeObserver.
scrollDuration
number
scrollEasing
string

API

Slots

Content slots exposed by this component.

#item
#default
Template for each rendered item. Receives item (raw value from items array) and index.
#item.renderless
Alternative slot used in renderless mode. Receives itemRef which must be bound to the root element so the ResizeObserver can measure height.

API

Exposed members

Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.

(index: number) => void
Programmatically scrolls to bring the item at the given index into view.
<T extends object>(props: T, exclude?: string[]) => Partial<T>
Utility to forward a filtered subset of props.
Ref<string>
Reactive CSS string for computed styles.
string
Unique style-sheet ID.
() => void
Injects the style sheet on mount.
() => void
Removes the style sheet on unmount.
Ref<boolean>
True once the style sheet has been injected.

Customisation

CSS variables

CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.

Default estimated item height used for initial spacer calculation (48px = standard list row).
scroll-padding on the scroll container, so focused items are not obscured by sticky headers.
Item appear/disappear transition duration (fast to avoid jank during rapid scrolling).

Inclusion

Accessibility

ARIA roles, keyboard navigation and focus management. Sourced from the real component template.

Keyboard interactions

Keyboard interactions
KeyAction
TabFocuses the scroll container, then navigates through rendered items.
ArrowDown / ArrowUpScrolls the list when the container has focus.

Notes

  • Only visible items are in the DOM — screen readers may announce fewer items than the total count. Add aria-setsize and aria-posinset on each rendered item if the total count matters semantically.
  • When scrollToIndex is called programmatically, focus management is the consumer responsibility. Items outside the visible window are unmounted and cannot receive focus.

Foundation

Design tokens

Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.

Source
dimension
48px
Default estimated item height.
duration
var(--origam-motion__duration---fast)
Item transition duration.
dimension
var(--origam-space---0)
Scroll container scroll-padding.

Interactive

Playground

Edit props live and see the component update in real time. The generated code snippet updates as you change values.

Rendering the live preview…

Usage

Examples

Ready-to-paste code snippets for your templates.

Basic virtual list

vue

Fixed item height (optimised)

vue