VirtualScroll
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…
wrapperRendering the live preview…
fixed heightRendering the live preview…
renderlessStructure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<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.
- itemsArray<any>[]
- Source array of items to virtualize. Can contain any value — the type is forwarded as-is to the #default slot.
- renderlessbooleanfalse
- 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.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- overscannumber2
- Number of items rendered outside the visible window for smooth scrolling. Higher values reduce blank flashes but increase DOM size.
- heightnumber | string
- Height of the scroll container. Required unless renderless=true.
- maxHeightnumber | string
- Maximum height for the container (used with auto-height layouts).
- maxWidthnumber | string
- minHeightnumber | string
- minWidthnumber | string
- widthnumber | string
- itemHeightnumber | stringnull
- Estimated (or fixed) item height in pixels. Used for initial spacer calculation. When null, item heights are measured dynamically via ResizeObserver.
- scrollDurationnumber
- scrollEasingstring
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
| Key | Action |
|---|---|
| Tab | Focuses the scroll container, then navigates through rendered items. |
| ArrowDown / ArrowUp | Scrolls 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.
- dimension48px
- Default estimated item height.
- durationvar(--origam-motion__duration---fast)
- Item transition duration.
- dimensionvar(--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
Fixed item height (optimised)