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.
Aperçu
Rendu de l’aperçu en cours…
wrapperRendu de l’aperçu en cours…
fixed heightRendu de l’aperçu en cours…
renderlessStructure
Anatomie
Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.
<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.
- 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
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
| Touche | 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.
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.
- dimension48px
- Default estimated item height.
- durationvar(--origam-motion__duration---fast)
- Item transition duration.
- dimensionvar(--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
Fixed item height (optimised)