LayoutReact
A stream of content that loads more at its end, and optionally at its start, as the reader reaches it.
Rendered by React 19.3.1
Installation
npm i @hamur/reactNot on npm yet. The package goes out under the chosen name.
Anatomy
Import the component and assemble its parts:
<InfiniteScroll.Root>
<InfiniteScroll.Feed>
<InfiniteScroll.Article />
</InfiniteScroll.Feed>
<InfiniteScroll.Sentinel>
<InfiniteScroll.Loading />
</InfiniteScroll.Sentinel>
</InfiniteScroll.Root>
// Not in this example: InfiniteScroll.End, InfiniteScroll.Error, InfiniteScroll.TriggerExamples
Manual
mode="manual" with a Load more button; the second page fails once and the same button, now Try again, retries.
Start
A conversation opened at its newest message: hasMoreStart and a start Sentinel load older ones above while the reading position holds.
Virtualized
10,000 posts loaded 50 at a time with the Virtualizer inside the Feed; totalCount keeps each place right.
End
25 posts in five pages; once the last arrives End replaces Loading and the end is announced.
API reference
24 props across 8 parts, in React syntax. className, style, render are listed once, under Shared props.
ArticleInfiniteScroll.Article
One item of the feed. Holds the feed's single Tab stop when it last held focus. Name it with aria-labelledby pointing at its title. Renders an <article>.
| Prop | Type | Default |
|---|---|---|
indexThe article's 0-based place among the loaded items. | number | — |
| Data attribute | Description |
|---|---|
data-index | The article's 0-based place among the loaded items. |
EndInfiniteScroll.End
Renders its children only when its side has no more to load, such as "No more posts", or "No results" for an empty feed. Renders a <div>.
| Prop | Type | Default |
|---|---|---|
sideThe side whose state the part shows. | InfiniteScrollSide | 'end' |
| Data attribute | Description |
|---|---|
data-side | The side whose state the part shows. |
ErrorInfiniteScroll.Error
Renders its children only while its side's last load failed, such as a message beside the Trigger that retries. Renders a <div>.
| Prop | Type | Default |
|---|---|---|
sideThe side whose state the part shows. | InfiniteScrollSide | 'end' |
| Data attribute | Description |
|---|---|
data-side | The side whose state the part shows. |
FeedInfiniteScroll.Feed
The feed of articles: aria-busy while a side loads, and the Page Up, Page Down, Control + Home and Control + End keys. Name it with aria-label or aria-labelledby. Renders a <div>.
| Data attribute | Description |
|---|---|
data-loading | Present while either side loads. |
LoadingInfiniteScroll.Loading
Renders its children only while its side loads, such as a spinner or skeletons. Renders a <div>.
| Prop | Type | Default |
|---|---|---|
sideThe side whose state the part shows. | InfiniteScrollSide | 'end' |
| Data attribute | Description |
|---|---|
data-side | The side whose state the part shows. |
RootInfiniteScroll.Root
Groups an infinite scroll: a stream of content that loads more at its end, and optionally at its start, as the user reaches it. Holds both sides' state and renders the status region after its children. Renders a <div>.
| Prop | Type | Default |
|---|---|---|
onLoadMoreCalled when a side should load more. | ((eventDetails: InfiniteScrollLoadDetails) => void | Promise<unknown>) | — |
hasMoreWhether the end side has more to load. | boolean | true |
loadingWhether the end side is loading. | boolean | — |
errorWhether the end side's last load failed. | boolean | — |
hasMoreStartWhether the start side has more to load. | boolean | false |
loadingStartWhether the start side is loading. | boolean | — |
errorStartWhether the start side's last load failed. | boolean | — |
modeWhether a side loads when the user nears it (auto) or only from a Trigger (manual). | InfiniteScrollMode | 'auto' |
thresholdHow close, in px, a Sentinel comes to the scroller's visible edge before its side loads. | number | 300 |
maxAutoLoadsThe automatic loads per side, since mount or reset(), after which the side loads only from | number | Infinity |
itemCountThe number of loaded items. | number | — |
totalCountThe number of items there are in all, written as aria-setsize; -1 when unknown. | number | — |
orientationThe axis the content scrolls along. | InfiniteScrollOrientation | 'vertical' |
disabledWhether no load starts. | boolean | false |
labelsThe texts of the status messages. | Partial<InfiniteScrollLabels> | — |
actionsRefA ref to imperative actions: loadMore(side) and reset(). | React.Ref<InfiniteScrollActions> | — |
| Data attribute | Description |
|---|---|
data-loading | Present while either side loads. |
data-empty | Present when no item is loaded and no side loads. |
data-disabled | Present when the infinite scroll is disabled. |
SentinelInfiniteScroll.Sentinel
The edge a side loads from when the user nears it, placed before the Feed (start) or after it (end), and the container of that side's Trigger, Loading, Error and End. Renders a <div>.
| Prop | Type | Default |
|---|---|---|
sideThe side the sentinel loads: start before the Feed, end after it. | InfiniteScrollSide | 'end' |
| Data attribute | Description |
|---|---|
data-side | The side the sentinel loads. |
data-status | The side's status. |
data-paused | Present while the side does not load automatically: manual mode, or after maxAutoLoads. |
TriggerInfiniteScroll.Trigger
A button that loads its side now, and retries after an error. Rendered only while its side has more; aria-disabled and still focusable while its side loads. Renders a <button>.
| Prop | Type | Default |
|---|---|---|
sideThe side the trigger loads. | InfiniteScrollSide | 'end' |
focusableWhenDisabledWhether the button stays focusable while its side loads or the Root is disabled. | boolean | true |
nativeButtonWhether the component renders a native <button> element when replacing it | boolean | true |
| Data attribute | Description |
|---|---|
data-side | The side the trigger loads. |
data-loading | Present while its side loads. |
data-disabled | Present when the infinite scroll is disabled. |
Shared props
Every part that renders an element takes these.
| Prop | Type |
|---|---|
classNameCSS class applied to the element, or a function that
returns a class based on the component's state. | string | ((state: State) => string | undefined) |
styleStyle applied to the element, or a function that
returns a style object based on the component's state. | React.CSSProperties | ((state: State) => React.CSSProperties | undefined) |
renderAllows you to replace the component's HTML element
with a different tag, or compose it with another component. | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, State> |
Keyboard and accessibility
Keyboard
| Keys | Does | Part |
|---|---|---|
| Page Down | Moves focus to the next Article; at the last one, loads the end side (in manual mode, focuses its Trigger) | Feed |
| Page Down | At the last Article in manual mode, focuses the end Trigger without a load | Feed |
| Page Up | Moves focus to the previous Article; at the first, the same for the start side | Feed |
| ControlEndControlHome | Moves focus to the first focusable element after or before the Feed | Feed |
Accessibility
| Part | Sets | So that |
|---|---|---|
| Root | a role="status" region, polite and atomic | a load that runs long, an error, the new items and the end are each said once, outside the busy feed |
| Feed | role="feed", aria-busy="true" while a side loads, named by aria-label or aria-labelledby | assistive technology waits for the new items before it reads on |
| Article | aria-posinset and aria-setsize, one Tab stop (tabindex 0 on the current one, -1 on the others) | the reader hears "post 11 of 25" and the page has one tab stop in the feed |
| Sentinel | data-side and data-status, no role | the edge can be styled by what it is doing |
| Trigger | a button with aria-disabled while its side loads | the keyboard and screen reader path to load, retry or continue; it keeps focus while it loads |
| Error | rendered only while its side failed | the failure is on the page and in the status region |
| End | rendered only when its side has no more | the reader knows the feed is whole |
Focus order
- Each
Articleis a tab stop only while it is the current one;Tableaves theFeedfor the next control, andPage DownandPage Upmove between theArticles. - A control inside an
Articlekeeps its place in the tab order. - The
Triggercomes after theFeed(or before it, for the start side) and is reached byTab. - When a
Triggerends its own side, focus goes to the outermostArticleinstead of falling to the page.