InfiniteScrolling

The ItemsProvider is the only required parameter: it receives the number of the items already loaded as the Skip of its request and returns the next page. The component renders each returned item with its child content, appends it to the list, and then waits for the sentinel element at the end of the list to come into view again, so the next page is fetched only when the user actually gets there. While a page is in flight, the default Loading... text is rendered under the items.

The content of the component is replaceable: ItemTemplate (an alias of the child content) renders each item, and LoadingTemplate replaces the loading text while a page is being fetched. The plain-text variant of the latter is also configurable through the LoadingMessage parameter, which is enough when no markup is needed. Whatever they render, the state the list is in is also announced to screen readers by a live region the component keeps in the DOM.

The empty state is rendered only when the very first page comes back without a single item, and never alongside any item. Its text comes from EmptyMessage, and EmptyTemplate replaces it with markup of your own. Both lists below are fed by a provider that returns no item.

Setting PageSize sends the size of the page to the provider as the Count of its request, so the query knows how many items to take. It also tells the component where the data ends: a page that comes back with fewer items than requested is the last one, which saves the extra empty round trip that would otherwise be needed to discover the end. Once there is nothing left to fetch, the EndMessage is rendered after the last item and the sentinel stops being watched; EndTemplate replaces that message with markup of your own.

The Manual parameter replaces the automatic loading with an explicit button: the first page is still fetched on its own, but every next one waits for a click. This is the accessible fallback of an infinite list - it keeps the page footer reachable and gives keyboard and screen reader users a real control to operate - and it is also the polite choice on metered connections. The label of the button comes from LoadMoreText, and LoadMoreTemplate replaces its content entirely. The button keeps its place while the page it asked for is loading, disabled rather than removed, so the keyboard focus that pressed it is not dropped back to the top of the page.

An items provider that throws no longer takes the whole list down with it: the exception is caught, the ErrorMessage is rendered with a retry button, and the sentinel stops being watched so a failing endpoint cannot turn the list into a request storm. Clicking retry (or calling LoadMoreAsync) requests the same page again and the list continues from where it stopped - the button stays where it is, disabled and still labelled RetryText, until that retry is over. Use ErrorTemplate, which receives the thrown exception, to render the failure your own way - it replaces the built-in retry button too, so it should offer a way back of its own. Both lists below fail once, on their second page.

The Reversed parameter turns the list into a chat or a log: the sentinel moves to the top, each page is prepended above the already rendered items, and the component starts out scrolled to the newest ones. Scrolling up loads the older items while the scroll position is corrected around every insertion, so the item the user is reading stays exactly where it is instead of being pushed down the viewport. The loading, end and Load more blocks follow the sentinel to the top, which is where they belong in this mode.

By default the root element of the component is its own scroll container. ScrollerSelector points it at another one instead, and the window value (like document, body and html) means the page itself scrolls, which is the layout of a feed that has no box of its own. A component that hands its scrolling over this way stops clipping and scrolling its own content. RootMargin grows the area the sentinel is checked against, so 200px starts the next page 200 pixels before the end of the list becomes visible and the list stays ahead of the reader. LastElementHeight gives the sentinel a real height, which is the coarser way of triggering the load earlier, and Threshold then decides how much of that height has to be visible before the load starts. Preload fetches the first page during initialization so prerendered markup is not empty.

OnItemsLoaded is invoked after each successful page with the items of that page only, which is where analytics, an updated counter, or a URL that reflects the loaded range belong. OnEnd fires once, when the provider reports that nothing is left, and OnError hands over the exception that a failed page threw.

Loaded pages: 0, loaded items: 0

A reference to the component exposes what it has loaded so far (Items, HasMore, IsLoading, TotalCount and the Error of the last failed page) and the methods to drive it: RefreshDataAsync throws the loaded items away and starts over from the first page, LoadMoreAsync fetches the next page the way reaching the end of the list does, AppendItemsAsync, PrependItemsAsync, SetItemsAsync and RemoveItemAsync change the loaded items without calling the provider at all, and ScrollToTopAsync, ScrollToBottomAsync, ScrollToOffsetAsync and GetScrollOffsetAsync read and move the scroll container - the last two are what restore the position of a list the user is coming back to. The MaxItems parameter used here also caps the list: the last page is narrowed down to what is still missing and nothing is requested afterwards, so the list never grows past the cap.

Items: 0   HasMore:   IsLoading:   Offset: 0

A provider can return a BitInfiniteScrollingItemsProviderResult instead of a plain sequence. It is an IEnumerable of the same page, so nothing else changes, but it also carries HasMore and TotalCount. HasMore lets the source say for itself where the data ends, which is what a cursor-paged API knows and a short page cannot express; TotalCount is published on the TotalCount member of the component, which is how a list reports the progress it has made through a known total.

Loaded 0 of ? items.

Horizontal lays the items out in a row and moves the whole component onto the horizontal axis: the pages are fetched while scrolling sideways, the sentinel becomes a thin column at the end of the row - sized by LastElementWidth rather than by LastElementHeight - and ScrollToTopAsync, ScrollToBottomAsync and ScrollToOffsetAsync all work along that axis, right-to-left lists included. Give the items a flex: 0 0 auto so the row grows past the width of the container instead of squeezing them into it.

Without a key an item is matched by its position, so a page prepended above the rendered items rewrites the content of every node below it - which is both the slow way to insert a page and the reason the state a node holds on its own (the text in an input, a running animation, the caret) ends up next to the wrong item. ItemKey returns a stable key per item, and the items are matched by that key instead. Type a note next to a message below, then scroll up to load the older ones: the note stays with its own message.

A provider written as a lambda that captures a filter is the same method on every render, so a changed filter cannot be told apart from a re-render of the parent - and reloading on the delegate alone would throw the list away every time the parent renders. ResetKey is what settles it: hand the filter (or anything derived from it) to the component and every change of that value refreshes the list from its first page, exactly like calling RefreshDataAsync.

The Style and Class parameters style the root element, while Styles and Classes reach the inner parts of the component - the sentinel (LastElement), the Loading, Empty, End and Error containers, and the Button of the manual and retry states. The LastElementClass, LastElementStyle, LastElementHeight and LastElementWidth parameters remain the shorthand for the sentinel alone.

Set Dir to BitDir.Rtl to render the list right-to-left. The items, the status blocks and the button of the manual and retry states all flip along with it, and a horizontal list scrolls from the right.