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.

Aperçu

Rendu de l’aperçu en cours…

wrapper

Rendu de l’aperçu en cours…

fixed height

Rendu de l’aperçu en cours…

renderless

Structure

Anatomie

Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.

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

Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et 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

Emplacements de contenu exposés par ce composant.

#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

Membres exposés

Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.

(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.

Personnalisation

Variables CSS

Propriétés CSS personnalisées exposées par ce composant. Surchargez-les pour personnaliser sans perdre la compatibilité avec le thème.

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

Accessibilité

Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.

Interactions clavier

Interactions clavier
ToucheAction
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.

Fondation

Design tokens

Extrait des tokens de ce composant — les variables --origam-<composant>---<propriété>, déclarées dans sa feuille de tokens tenue à la main, sans étape de build.

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.

Interactif

Playground

Modifiez les props en direct et observez le composant se mettre à jour. Le snippet de code généré suit vos changements.

Rendu de l’aperçu en cours…

Usage

Exemples

Extraits de code prêts à coller dans vos templates.

Basic virtual list

vue

Fixed item height (optimised)

vue