Virtualized lists for Hotwire
npm install hotwire-virtualizedVirtualized lists for Hotwire using Stimulus and Turbo Streams.
A minimal example within a Rails app can be found here.
``html
data-virtualized-row-height-value="50"
data-virtualized-url-value="/load-items"
data-virtualized-ids-value="[1,2,3,4,5]"
style="height: 100vh"
>
Turbo Actions
This library uses custom actions to interact with the virtualized list.
$3
html
ID {id}
`$3
html
`$3
html
ID 6
`Stimulus Actions
$3
html
data-virtualized-id-param="123"
data-virtualized-action-param="prepend"
>
Prepend ID
`$3
html
data-virtualized-id-param="123"
data-virtualized-action-param="append"
>
Append ID
`Emitting Events
Within a controller in your app, dispatch an event which includes:
- id: The unique ID of this row, possibly to fetch from backend.
- action: The action to perform, one of
, append, remove, before, after, replace.
- element: The HTML element to be inserted, if left blank, virtualized will fetch from backend using id.
- targetId: When action is "before" or "after" or "replace" used to place relative to another row.
- virtualizedId: When multiple virtualized controllers are on the page, this is used to target a specific instance.`js
const { id, element } = this.buildElement();
this.dispatch("emit", {
detail: { id, element, action: "append", scrollTo: true },
});
`Catch the event and forward it to the virtualized controller's
action:`html
data-action="event:emit->virtualized#eventRender"
>Actions
$3
The
action can be called to prepend, append, insert, remove, etc... rows.Require params:
- id: The unique ID of this row, possibly to fetch from backend.
- action: What action to perform
- prepend
- append
- after
- before
- replace
- remove
- targetId: when the action is relative
- selector: used to find element to add to cache via
document.querySelector(selector)Preload Data
By default, the virtualized controller will fetch data from the backend for any IDs that aren't in its row cache. You can preload data into the row cache using the
target. This is useful when you want to render the first set of rows immediately.You must pass a data attribute of
data-preloaded-id="1" where 1 is the ID that corresponds to the row, as it is how we correspond this row to the data in the row cache.`html
Preloaded 1
Preloaded 2
`Multiple Virtualized
When you require multiple instances on a single page, you must set the
value to a unique value for each instance. The default value when not set is virtualized.`html
data-virtualized-virtualized-id-value="virtual-a"
>
data-virtualized-virtualized-id-value="virtual-b"
>
$3
When stream responses need to target a specific instance must include the
attribute:`html
Content
`$3
Events can also be targeted towards a specific instance using the
detail value:`js
this.dispatch("emit", {
detail: { id, element, action: "prepend", virtualizedId: "virtual-a" },
});
`$3
Requests to load data from the server will include the
header value in order to differentiate requests being made by different instances.Scrolling
You can call the
scrollTop or scrollBottom actions to scroll to the top or bottom of the list.`html
``