Skip to content

docs: expand accessibility props in README #433

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
iamdarshshah merged 2 commits into from
Jun 6, 2026
Merged

docs: expand accessibility props in README #433

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b4016b9
docs: add accessibility props to table and usage examples
iamdarshshah Jun 6, 2026
cccf1d6
docs: add sayedrisat to contributors list
iamdarshshah Jun 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 64 additions & 23 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->

[![All Contributors](https://img.shields.io/badge/all_contributors-27-orange.svg?style=flat-square)](#contributors-)
[![All Contributors](https://img.shields.io/badge/all_contributors-28-orange.svg?style=flat-square)](#contributors-)

<!-- ALL-CONTRIBUTORS-BADGE:END -->

Expand Down Expand Up @@ -340,28 +340,68 @@ function PostList() {

## Props, `InfiniteScroll`

| Prop | Type | Required | Default | Description |
| ---------------------------- | ---------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dataLength` | `number` | yes | - | Current count of rendered items. The component resets its load guard each time this value changes, which allows `next()` to fire again on the next scroll. |
| `next` | `() => void` | yes | - | Called once when the sentinel enters the viewport. Append new items to your list state inside this callback; do not replace the existing items. |
| `hasMore` | `boolean` | yes | - | When `false`, the observer is disconnected and `next()` will not be called again. Set it to `false` when your data source has no more pages. |
| `loader` | `ReactNode` | yes | - | Rendered below the list while the next page is loading. Displayed between the last item and the bottom sentinel. |
| `endMessage` | `ReactNode` | no | - | Rendered below the list when `hasMore` is `false`. Use it for an "all caught up" or "no more items" message. |
| `height` | `number \| string` | no | - | Creates a fixed-height scroll container wrapping the list. Accepts a pixel number or any CSS length string. Omit this prop to scroll the window instead. |
| `scrollableTarget` | `HTMLElement \| string \| null` | no | - | The scrollable ancestor that already provides overflow scrollbars. Pass the element's `id` string or a direct `HTMLElement` reference. Required when the scroll container is neither the window nor the `height` wrapper. |
| `scrollThreshold` | `number \| string` | no | `0.8` | How close to the bottom the user must scroll before `next()` is called. A fraction like `0.8` means 80% scrolled; a string like `"200px"` means within 200 px of the bottom edge. |
| `inverse` | `boolean` | no | `false` | Reverse scroll direction for chat or messaging UIs. The sentinel moves to the top of the list. Use together with `flexDirection: column-reverse` on the scroll container. |
| `pullDownToRefresh` | `boolean` | no | `false` | Enable pull-to-refresh gesture on touch and mouse. Requires `refreshFunction` to also be set. |
| `refreshFunction` | `() => void` | no | - | Called once when the user pulls down past `pullDownToRefreshThreshold` pixels and releases. Only active when `pullDownToRefresh` is `true`. |
| `pullDownToRefreshThreshold` | `number` | no | `100` | How many pixels the user must pull down before `refreshFunction` is triggered on release. |
| `pullDownToRefreshContent` | `ReactNode` | no | - | Content shown inside the pull-to-refresh area while the user is pulling but has not yet reached the threshold. |
| `releaseToRefreshContent` | `ReactNode` | no | - | Content shown inside the pull-to-refresh area once the threshold is passed and the user can release to trigger a refresh. |
| `onScroll` | `(e: UIEvent) => void` | no | - | Callback fired on every scroll event on the container. Receives the native `UIEvent`. Useful for syncing UI state with scroll position. |
| `className` | `string` | no | `''` | CSS class name applied to the inner scroll container div. |
| `style` | `CSSProperties` | no | - | Inline style object applied to the inner scroll container div. Merged with the component's default layout styles. |
| Accessibility attributes | `aria-*`, `role`, `tabIndex`, `id` | no | - | Accessibility attributes applied to the inner scroll container div for labelling, semantics, and keyboard focus management. |
| `hasChildren` | `boolean` | no | - | Set to `true` when `children` is a single element or a fragment rather than an array. Helps the component detect whether visible content exists to determine scroll state. |
| `initialScrollY` | `number` | no | - | Scrolls the window to this Y offset on mount. Useful for restoring a user's scroll position when navigating back to a page. |
| Prop | Type | Required | Default | Description |
| ---------------------------- | ------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dataLength` | `number` | yes | - | Current count of rendered items. The component resets its load guard each time this value changes, which allows `next()` to fire again on the next scroll. |
| `next` | `() => void` | yes | - | Called once when the sentinel enters the viewport. Append new items to your list state inside this callback; do not replace the existing items. |
| `hasMore` | `boolean` | yes | - | When `false`, the observer is disconnected and `next()` will not be called again. Set it to `false` when your data source has no more pages. |
| `loader` | `ReactNode` | yes | - | Rendered below the list while the next page is loading. Displayed between the last item and the bottom sentinel. |
| `endMessage` | `ReactNode` | no | - | Rendered below the list when `hasMore` is `false`. Use it for an "all caught up" or "no more items" message. |
| `height` | `number \| string` | no | - | Creates a fixed-height scroll container wrapping the list. Accepts a pixel number or any CSS length string. Omit this prop to scroll the window instead. |
| `scrollableTarget` | `HTMLElement \| string \| null` | no | - | The scrollable ancestor that already provides overflow scrollbars. Pass the element's `id` string or a direct `HTMLElement` reference. Required when the scroll container is neither the window nor the `height` wrapper. |
| `scrollThreshold` | `number \| string` | no | `0.8` | How close to the bottom the user must scroll before `next()` is called. A fraction like `0.8` means 80% scrolled; a string like `"200px"` means within 200 px of the bottom edge. |
| `inverse` | `boolean` | no | `false` | Reverse scroll direction for chat or messaging UIs. The sentinel moves to the top of the list. Use together with `flexDirection: column-reverse` on the scroll container. |
| `pullDownToRefresh` | `boolean` | no | `false` | Enable pull-to-refresh gesture on touch and mouse. Requires `refreshFunction` to also be set. |
| `refreshFunction` | `() => void` | no | - | Called once when the user pulls down past `pullDownToRefreshThreshold` pixels and releases. Only active when `pullDownToRefresh` is `true`. |
| `pullDownToRefreshThreshold` | `number` | no | `100` | How many pixels the user must pull down before `refreshFunction` is triggered on release. |
| `pullDownToRefreshContent` | `ReactNode` | no | - | Content shown inside the pull-to-refresh area while the user is pulling but has not yet reached the threshold. |
| `releaseToRefreshContent` | `ReactNode` | no | - | Content shown inside the pull-to-refresh area once the threshold is passed and the user can release to refresh. |
| `onScroll` | `(e: UIEvent) => void` | no | - | Callback fired on every scroll event on the container. Receives the native `UIEvent`. Useful for syncing UI state with scroll position. |
| `className` | `string` | no | `''` | CSS class name applied to the inner scroll container div. |
| `style` | `CSSProperties` | no | - | Inline style object applied to the inner scroll container div. Merged with the component's default layout styles. |
| `role` | `AriaRole` | no | - | Semantic role for the scroll container. Use `"list"` for item lists, `"feed"` for activity streams. |
| `tabIndex` | `number` | no | - | Makes the scroll container focusable. Pass `0` to include it in the natural tab sequence. |
| `id` | `string` | no | - | DOM id for the container. Useful when other elements reference it via `aria-labelledby`. |
| `aria-*` | `AriaAttributes` | no | - | Any React `aria-*` prop (`aria-label`, `aria-labelledby`, `aria-describedby`, etc.) forwarded to the scroll container. |
| `hasChildren` | `boolean` | no | - | Set to `true` when `children` is a single element or a fragment rather than an array. Helps the component detect whether visible content exists to determine scroll state. |
| `initialScrollY` | `number` | no | - | Scrolls the window to this Y offset on mount. Useful for restoring a user's scroll position when navigating back to a page. |

## Accessibility

Pass `role` and a label so screen readers can announce the container and its item count correctly:

```tsx
<InfiniteScroll
role="list"
aria-label="Search results"
dataLength={items.length}
next={fetchMore}
hasMore={hasMore}
loader={<p>Loading...</p>}
>
{items.map((item) => (
<div role="listitem" key={item.id}>
{item.name}
</div>
))}
</InfiniteScroll>
```

Or reference an existing heading via `aria-labelledby`:

```tsx
<h2 id="results-heading">Search results</h2>
<InfiniteScroll
role="list"
aria-labelledby="results-heading"
dataLength={items.length}
next={fetchMore}
hasMore={hasMore}
loader={<p>Loading...</p>}
>
```

---

## Props, `useInfiniteScroll`

Expand Down Expand Up @@ -447,6 +487,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
<td align="center" valign="top" width="14.28%"><a href="https://github.com/leonh"><img src="https://avatars.githubusercontent.com/u/57818?v=4?s=80" width="80px;" alt="ludwig404"/><br /><sub><b>ludwig404</b></sub></a><br /><a href="https://github.com/ankeetmaini/react-infinite-scroll-component/commits?author=leonh" title="Code">💻</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/fooki"><img src="https://avatars.githubusercontent.com/u/196968708?v=4?s=80" width="80px;" alt="Karl Johansson"/><br /><sub><b>Karl Johansson</b></sub></a><br /><a href="https://github.com/ankeetmaini/react-infinite-scroll-component/commits?author=fooki" title="Code">💻</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/geoffreyteng"><img src="https://avatars.githubusercontent.com/u/8918254?v=4?s=80" width="80px;" alt="Geoffrey Teng"/><br /><sub><b>Geoffrey Teng</b></sub></a><br /><a href="https://github.com/ankeetmaini/react-infinite-scroll-component/commits?author=geoffreyteng" title="Code">💻</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/sayedrisat"><img src="https://avatars.githubusercontent.com/u/197038753?v=4?s=80" width="80px;" alt="Sayed Risat"/><br /><sub><b>Sayed Risat</b></sub></a><br /><a href="https://github.com/ankeetmaini/react-infinite-scroll-component/commits?author=sayedrisat" title="Code">💻</a> <a href="https://github.com/ankeetmaini/react-infinite-scroll-component/commits?author=sayedrisat" title="Documentation">📖</a></td>
</tr>
</tbody>
</table>
Expand Down
Loading