docs: Async load more documentation for RAC #8431

LFDanLu · 2025-06-20T21:17:10Z

Closes

✅ Pull Request Checklist:

Included link to corresponding React Spectrum GitHub Issue.
Added/updated unit tests and storybook for this change (for new code or code which already has tests).
Filled out test instructions.
Updated documentation (if it already exists for this component).
Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

🧢 Your Project:

rspbot · 2025-06-20T21:22:05Z

Build successful! 🎉

rspbot · 2025-06-20T21:27:19Z

Build successful! 🎉

rspbot · 2025-06-20T21:33:48Z

Build successful! 🎉

LFDanLu · 2025-06-20T21:19:01Z

packages/react-aria-components/docs/ComboBox.mdx

+<details>
+  <summary style={{fontWeight: 'bold'}}><ChevronRight size="S" /> MyProgressCircle</summary>
+
+```tsx example export=true render=false
+import {ProgressBar} from 'react-aria-components';
+import type {ProgressBarProps} from 'react-aria-components';
+
+export function MyProgressCircle(props: ProgressBarProps) {
+  return (
+    <ProgressBar {...props}>
+      <svg width="24" height="24" viewBox="0 0 24 24" style={{display: 'block'}}>
+        <path fill="currentColor" d="M12,1A11,11,0,1,0,23,12,11,11,0,0,0,12,1Zm0,19a8,8,0,1,1,8-8A8,8,0,0,1,12,20Z" opacity=".25" />
+        <path fill="currentColor" d="M10.14,1.16a11,11,0,0,0-9,8.92A1.59,1.59,0,0,0,2.46,12,1.52,1.52,0,0,0,4.11,10.7a8,8,0,0,1,6.66-6.61A1.42,1.42,0,0,0,12,2.69h0A1.57,1.57,0,0,0,10.14,1.16Z">
+          <animateTransform attributeName="transform" type="rotate" dur="0.75s" values="0 12 12;360 12 12" repeatCount="indefinite"/>
+        </path>
+      </svg>
+    </ProgressBar>
+  );
+}
+```


This gets used in a bunch of other places, what do people think about including it in the reusable wrappers in ProgressBar docs so we can import it?

LFDanLu · 2025-06-20T21:19:40Z

packages/react-aria-components/docs/ComboBox.mdx

-[this CodeSandbox](https://codesandbox.io/s/dreamy-burnell-3i2jy?file=/src/Autocomplete.tsx) for an example
-of a ComboBox supporting those features.


got rid of the codesandbox since this has a direct example now, that sandbox is referenced in the hook docs anyways

LFDanLu · 2025-06-20T21:21:26Z

packages/react-aria-components/docs/Table.mdx

+  .react-aria-TableHeader {
+    position: sticky;
+    top: 0;
+    background: white;
+    z-index: 1;
+  }


this has a weird shift in vertical position when scrolling down, haven't quite figured out why exactly

LFDanLu · 2025-06-20T21:23:01Z

packages/react-aria-components/docs/Tree.mdx

+Note that `<TreeLoadMoreItem>` is meant to render the spinner specifically when loading additional items,
+the initial loading state and empty state should instead be handled via [renderEmptyState](#empty-state).
+
+```tsx example


Example is quite long, I could pull out the interfaces but open to ideas if people have any ideas

hmm yeah, we can collapse some stuff in the new docs. Nice to show two separate lists here though I think, especially since we don't have useAsyncTree.

…m into docs_for_load_spinner

rspbot · 2025-06-23T17:48:19Z

Build successful! 🎉

rspbot · 2025-06-23T18:53:20Z

Build successful! 🎉

rspbot · 2025-06-24T21:28:25Z

Build successful! 🎉

snowystinger

Need to update for dark mode as well

snowystinger · 2025-06-26T05:54:55Z

packages/react-aria-components/docs/ComboBox.mdx

      inputValue={list.filterText}
      onInputChange={list.setFilterText}>
-      {(item) => <ListBoxItem id={item.name}>{item.name}</ListBoxItem>}
+      {/*- begin highlight -*/}


heh... this is a sorta confusing API. I see how it came about, and I don't have a different suggestion at this time since we're combining static items with dynamic
I guess we could show it by adding a "loading" item to the list.items and rendering the ListBoxLoadMoreItem when we get to that item, but then we might have to remember to remove it and move it to the end of the list

yeahhh, it certainly is. If definitely would be nice if it just lived in the list of items like you said but you've highlighted the exact reason why I didn't go that route haha (especially since it doesn't mesh very well with useAsyncList). In addition, having it statically added after your dynamic list ensures that it always exists in the collection so the loading sentinel is always rendered

packages/react-aria-components/docs/ComboBox.mdx

rspbot · 2025-06-26T17:35:18Z

Build successful! 🎉

devongovett · 2025-07-07T20:38:51Z

packages/react-aria-components/docs/GridList.mdx

+
+</details>
+
+### GridListLoadMoreItem


Can we move this under the Props section with the other components?

devongovett · 2025-07-07T20:47:27Z

packages/react-aria-components/docs/ComboBox.mdx

+      }
+
+      // Brief delay so spinner can be seen more easily
+      await new Promise(resolve => setTimeout(resolve, 500));


Do we want to keep this in the docs? Wouldn't be in a real implementation...

fair point, guess users could always slow down their network if they really wanted to see the spinner

behavior without these delays is a bit gross in the Tree example cuz you have to basically load all the pokemon/collapse the section if you want to get to the Star Wars Rree row since it loads so fast now, but maybe ok

more realistic I guess 🤷

devongovett · 2025-07-07T20:50:24Z

packages/react-aria-components/docs/ComboBox.mdx

+and filtering of data from a server. If you want to display a spinner to indicate the loading state to the user, or support features like
+infinite scroll to load more data, be sure to include the [`<ListBoxLoadMoreItem>`](../react-aria/ListBox.html#listboxloadmoreitem) after the `Listbox`'s items render function as shown in the example below.
+
+Note that `<ListBoxLoadMoreItem>` is meant to render the spinner specifically when loading additional items,
+the initial loading state and empty state should instead be handled via [renderEmptyState](../react-aria/ListBox.html#empty-state).


a bit shorter:

Suggested change

and filtering of data from a server. If you want to display a spinner to indicate the loading state to the user, or support features like

infinite scroll to load more data, be sure to include the [`<ListBoxLoadMoreItem>`](../react-aria/ListBox.html#listboxloadmoreitem) after the `Listbox`'s items render function as shown in the example below.

Note that `<ListBoxLoadMoreItem>` is meant to render the spinner specifically when loading additional items,

the initial loading state and empty state should instead be handled via [renderEmptyState](../react-aria/ListBox.html#empty-state).

and filtering of data from a server. Use the [renderEmptyState](../react-aria/ListBox.html#empty-state) prop to display a spinner during initial load. To enable infinite scrolling, render a [`<ListBoxLoadMoreItem>`](../react-aria/ListBox.html#listboxloadmoreitem) element at the end of the list.

devongovett · 2025-07-07T20:51:03Z

packages/react-aria-components/docs/GridList.mdx

+This example uses the [useAsyncList](../react-stately/useAsyncList.html) hook to handle asynchronous loading of data from a server. If you want to display a spinner to indicate the loading state to the user, or support features like
+infinite scroll to load more data, be sure to include the `<GridListLoadMoreItem>` after the `GridList`'s items render function as shown in the example below.
+
+Note that `<GridListLoadMoreItem>` is meant to render the spinner specifically when loading additional items,
+the initial loading state and empty state should instead be handled via [renderEmptyState](./empty-state).


same shortening as above.

devongovett · 2025-07-07T20:57:47Z

packages/react-aria-components/docs/Tree.mdx

+Note that `<TreeLoadMoreItem>` is meant to render the spinner specifically when loading additional items,
+the initial loading state and empty state should instead be handled via [renderEmptyState](#empty-state).
+
+```tsx example


hmm yeah, we can collapse some stuff in the new docs. Nice to show two separate lists here though I think, especially since we don't have useAsyncTree.

rspbot · 2025-07-07T22:06:50Z

Build successful! 🎉

…m into docs_for_load_spinner

rspbot · 2025-07-07T22:17:27Z

Build successful! 🎉

devongovett · 2025-07-07T23:31:05Z

packages/react-aria-components/docs/Select.mdx

-    async load({signal, filterText}) {
+    async load({signal, cursor, filterText}) {
+      // Brief delay so spinner can be seen more easily
+      await new Promise(resolve => setTimeout(resolve, 500));


remove this one too?

whoops, thanks for catching

rspbot · 2025-07-08T00:07:33Z

Build successful! 🎉

rspbot · 2025-07-08T02:37:46Z

Build successful! 🎉

…m into docs_for_load_spinner

rspbot · 2025-07-08T16:50:31Z

Build successful! 🎉

rspbot · 2025-07-08T16:50:32Z

## API Changes

react-aria-components

/react-aria-components:UNSTABLE_GridListLoadingSentinel

-UNSTABLE_GridListLoadingSentinel <T extends {}> {
-  children?: ReactNode
-  className?: string
-  isLoading?: boolean
-  onLoadMore?: () => any
-  scrollOffset?: number = 1
-  style?: CSSProperties
-}

/react-aria-components:UNSTABLE_ListBoxLoadingSentinel

-UNSTABLE_ListBoxLoadingSentinel <T extends {}> {
-  children?: ReactNode
-  className?: string
-  isLoading?: boolean
-  onLoadMore?: () => any
-  scrollOffset?: number = 1
-  style?: CSSProperties
-}

/react-aria-components:UNSTABLE_TableLoadingSentinel

-UNSTABLE_TableLoadingSentinel <T extends {}> {
-  children?: ReactNode
-  className?: string
-  isLoading?: boolean
-  onLoadMore?: () => any
-  scrollOffset?: number = 1
-  style?: CSSProperties
-}

/react-aria-components:UNSTABLE_TreeLoadingIndicator

-UNSTABLE_TreeLoadingIndicator <T extends {}> {
-  children?: ChildrenOrFunction<UNSTABLE_TreeLoadingIndicatorRenderProps>
-  className?: ClassNameOrFunction<UNSTABLE_TreeLoadingIndicatorRenderProps>
-  style?: StyleOrFunction<UNSTABLE_TreeLoadingIndicatorRenderProps>
-}

/react-aria-components:GridListLoadMoreItem

+GridListLoadMoreItem <T extends {}> {
+  children?: ReactNode
+  className?: string
+  isLoading?: boolean
+  onLoadMore?: () => any
+  scrollOffset?: number = 1
+  style?: CSSProperties
+}

/react-aria-components:ListBoxLoadMoreItem

+ListBoxLoadMoreItem <T extends {}> {
+  children?: ReactNode
+  className?: string
+  isLoading?: boolean
+  onLoadMore?: () => any
+  scrollOffset?: number = 1
+  style?: CSSProperties
+}

/react-aria-components:TableLoadMoreItem

+TableLoadMoreItem <T extends {}> {
+  children?: ReactNode
+  className?: string
+  isLoading?: boolean
+  onLoadMore?: () => any
+  scrollOffset?: number = 1
+  style?: CSSProperties
+}

/react-aria-components:TreeLoadMoreItem

+TreeLoadMoreItem <T extends {}> {
+  children?: ReactNode | ((TreeLoadMoreItemRenderProps & {
+    defaultChildren: ReactNode | undefined
+})) => ReactNode
+  className?: ClassNameOrFunction<TreeLoadMoreItemRenderProps>
+  isLoading?: boolean
+  onLoadMore?: () => any
+  scrollOffset?: number = 1
+  style?: StyleOrFunction<TreeLoadMoreItemRenderProps>
+}

/react-aria-components:GridListLoadMoreItemProps

+GridListLoadMoreItemProps {
+  children?: ReactNode
+  className?: string
+  isLoading?: boolean
+  onLoadMore?: () => any
+  scrollOffset?: number = 1
+  style?: CSSProperties
+}

/react-aria-components:ListBoxLoadMoreItemProps

+ListBoxLoadMoreItemProps {
+  children?: ReactNode
+  className?: string
+  isLoading?: boolean
+  onLoadMore?: () => any
+  scrollOffset?: number = 1
+  style?: CSSProperties
+}

/react-aria-components:TableLoadMoreItemProps

+TableLoadMoreItemProps {
+  children?: ReactNode
+  className?: string
+  isLoading?: boolean
+  onLoadMore?: () => any
+  scrollOffset?: number = 1
+  style?: CSSProperties
+}

/react-aria-components:TreeLoadMoreItemProps

+TreeLoadMoreItemProps {
+  children?: ReactNode | ((TreeLoadMoreItemRenderProps & {
+    defaultChildren: ReactNode | undefined
+})) => ReactNode
+  className?: ClassNameOrFunction<TreeLoadMoreItemRenderProps>
+  isLoading?: boolean
+  onLoadMore?: () => any
+  scrollOffset?: number = 1
+  style?: StyleOrFunction<TreeLoadMoreItemRenderProps>
+}

/react-aria-components:TreeLoadMoreItemRenderProps

+TreeLoadMoreItemRenderProps {
+  level: number
+}

…collection size (#8349) * Update tree and listlayout to handle multi loaders * adapting other stories to new loader api and adding useAsync example story * add tests * fix story for correctness, should only need to provide a dependecy at the top most collection * restoring focus back to the tree if the user was focused on the loader * fixing estimated loader position if sections exist taken from #8326 * skip test for now * revert loader keyboard focus specific logic * pulling over relevant code from focus_loading_spinners * modify tree to return item count when querying size * update TableCollection to return just the number of rows as size also the aria row index and pos in set from empty/isLoading state wrapper since it might be confusing to hear that there are items when the table/tree is empty * update other collection components to leverage item only count * clean up * properly prevent picker from opening where there arent items * fix lint * review comments * review comments * making the async stories not load forever * docs: Async load more documentation for RAC (#8431) * add docs for gridlist * add async loading docs for GridList and Listbox adjacent components * add docs example for table * add prop tables * rename sentinel component and add prop tables * adding tree docs for loading spinners * fix docs lint * typo and left over stuff * export the loadMoreItem props from the monopackage * review comments * fix the tree example in docs * review comments * review comments * forgot to remove a delay * review comments

LFDanLu added 7 commits June 19, 2025 11:49

add docs for gridlist

86939e3

add async loading docs for GridList and Listbox adjacent components

60ac8b2

add docs example for table

296f2b3

add prop tables

cc49d39

rename sentinel component and add prop tables

9895916

adding tree docs for loading spinners

4558617

fix docs lint

bc9b42e

typo and left over stuff

4ad2e2e

LFDanLu commented Jun 23, 2025

View reviewed changes

LFDanLu marked this pull request as ready for review June 23, 2025 16:39

LFDanLu added 2 commits June 23, 2025 10:35

Merge branch 'multi_loader_support' of github.com:adobe/react-spectru…

95be0b7

…m into docs_for_load_spinner

export the loadMoreItem props from the monopackage

74a5a1a

review comments

ac1e4cf

fix the tree example in docs

b6132a2

snowystinger approved these changes Jun 26, 2025

View reviewed changes

review comments

7eb72c4

LFDanLu added ready for review in sprint release labels Jun 26, 2025

devongovett reviewed Jul 7, 2025

View reviewed changes

review comments

4c70e5c

Merge branch 'multi_loader_support' of github.com:adobe/react-spectru…

0cf842b

…m into docs_for_load_spinner

devongovett reviewed Jul 7, 2025

View reviewed changes

forgot to remove a delay

d667c5c

Merge branch 'multi_loader_support' of github.com:adobe/react-spectru…

ef0a42a

…m into docs_for_load_spinner

devongovett approved these changes Jul 8, 2025

View reviewed changes

LFDanLu merged commit 4eab8de into multi_loader_support Jul 8, 2025
31 checks passed

LFDanLu deleted the docs_for_load_spinner branch July 8, 2025 17:34

		[this CodeSandbox](https://codesandbox.io/s/dreamy-burnell-3i2jy?file=/src/Autocomplete.tsx) for an example
		of a ComboBox supporting those features.


		</details>

		### GridListLoadMoreItem

docs: Async load more documentation for RAC #8431

docs: Async load more documentation for RAC #8431

Uh oh!

Conversation

LFDanLu commented Jun 20, 2025

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

Uh oh!

rspbot commented Jun 20, 2025

Uh oh!

rspbot commented Jun 20, 2025

Uh oh!

rspbot commented Jun 20, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rspbot commented Jun 23, 2025

Uh oh!

rspbot commented Jun 23, 2025

Uh oh!

rspbot commented Jun 24, 2025

Uh oh!

snowystinger left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rspbot commented Jun 26, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rspbot commented Jul 7, 2025

Uh oh!

rspbot commented Jul 7, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rspbot commented Jul 8, 2025

Uh oh!

rspbot commented Jul 8, 2025

Uh oh!

rspbot commented Jul 8, 2025

Uh oh!

rspbot commented Jul 8, 2025

react-aria-components

/react-aria-components:UNSTABLE_GridListLoadingSentinel

/react-aria-components:UNSTABLE_ListBoxLoadingSentinel

/react-aria-components:UNSTABLE_TableLoadingSentinel

/react-aria-components:UNSTABLE_TreeLoadingIndicator

/react-aria-components:GridListLoadMoreItem

/react-aria-components:ListBoxLoadMoreItem

/react-aria-components:TableLoadMoreItem