Infinite Scroll and Occlusion at > 60FPS
vertical-collection is an ember-addon that is part of the smoke-and-mirrors framework. It
focuses on improving initial and re-render performance in high-stress situations by providing a
component for performant lists and svelte renders to match a core belief:
Don't render the universe, render the scene.
- Ember.js v3.28.0 or above
- Ember CLI v4.4 or above
- Node.js v16 or above
Your web page is a universe, your viewport is the scene. Much like you wouldn't expect a video game to render out-of-scene content, your application should smartly cull the content it doesn't need to care about. Trimming excess content lets the browser perform both initial renders and re-renders at far higher frame-rates, as the only content it needs to focus on for layout is the content the user can see.
vertical-collection augments your existing app, it doesn't ask you to rewrite layouts or logic in order to use it.
It will try its best to allow you to keep the conventions, structures, and layouts you want.
ember install @html-next/vertical-collectionimport { VerticalCollection } from '@html-next/vertical-collection'
<template>
<VerticalCollection
@items={{items}}
@tagName="ul"
@estimateHeight={{50}}
@staticHeight={{false}}
@shouldRecycle={{true}}
@bufferSize={{1}}
@renderAll={{false}}
@renderFromLast={{false}}
@idForFirstItem={{idForFirstItem}}
@firstReached={{firstReachedCallback}}
@lastReached={{lastReachedCallback}}
@firstVisibleChanged={{firstVisibleChangedCallback}}
@lastVisibleChanged={{lastVisibleChangedCallback}}
as |item i|>
<li>
{{item.number}} {{i}}
</li>
</VerticalCollection>
</template>firstReached - Triggered when scroll reaches the first element in the collection
lastReached- Triggered when scroll reaches the last element in the collection
firstVisibleChanged - Triggered when the first element in the viewport changes
lastVisibleChanged - Triggered when the last element in the viewport changes
When an item scrolls out of the rendered range, the collection either keeps its rendered block for the item that scrolls in, or throws it away. shouldRecycle (default: true) picks between the two.
With @shouldRecycle={{true}}, the block goes into a pool and is reused. Glimmer sees the same {{#each}} key, so the components inside the block stay alive and only the yielded item and index change. While you scroll, no block is torn down and rendered again, so this path does less work.
With @shouldRecycle={{false}}, the block is destroyed, and the item that scrolls in gets a new block with new component instances.
Reuse is only safe if the block derives everything it renders from the yielded item and index. A reused block keeps all other state, and that state belongs to the item that was rendered there before. It shows stale content when the block holds:
{{unbound}}values;- state copied from arguments in a
constructor, aninit, or a class field; - state set once from an element modifier or from
didInsertElement; - uncontrolled DOM state, such as the scroll position of a nested element, text the user typed into an
<input>, or a running CSS transition.
The symptom is a row that renders values from a row you scrolled past. Prefer to make the block fully derived, because derived state is the better pattern anyway. Set @shouldRecycle={{false}} when you cannot.
vertical-collection version |
Supported Ember versions | Supported Node versions |
|---|---|---|
^v1.x.x |
v1.12.0 - v3.8.x |
? |
^v2.x.x |
v2.8.0 - v3.26.x |
v12 - ? |
^v3.x.x |
v2.18.0+ |
v14+ |
^v4.x.x |
v3.12.0+ |
v14+ |
Join the Ember community on Discord
Infinite scroll that remains performant even for very long lists is easily achievable
with the vertical-collection.
It works via a scrollable div or scrollable body.
If it can be trimmer, vertical-collection likes to trim it.
For updated documentation and demos see http://html-next.github.io/vertical-collection/
- Open an Issue for discussion first if you're unsure a feature/fix is wanted.
- Branch off of
master(default branch) - Use descriptive branch names (e.g.
<type>/<short-description>) - PR against
master(default branch).
Make sure you register the test waiter from ember-raf-scheduler. So ember-test-helpers's wait is aware of the scheduled updates.
An example can be found here
This project is licensed under the MIT License.