docs: Add Virtualizer docs #7700

devongovett · 2025-02-01T00:15:52Z

Closes #7361, closes #6751, closes #5707, closes #6981

Adds docs for Virtualizer with examples of list, grid, and table layouts, along with basic docs for custom collection renderers. Decided to only put these docs on a standalone Virtualizer page and not add examples to each individual component for now to keep the size of component pages down. We'll see how well people fined it.

Added padding and gap options to ListLayout while I was at it since I needed it for the examples.

Also removes UNSTABLE prefix from virtualizer exports. Did not yet remove it from collection renderer and collection builder stuff. Are we ready to do that? We will need to update the hook docs to use new collections at some point as well.

…er-docs

rspbot · 2025-02-01T00:18:51Z

Build successful! 🎉

rspbot · 2025-02-01T00:57:52Z

Build successful! 🎉

reidbarber

These look great!

packages/react-aria-components/src/Virtualizer.tsx

Co-authored-by: Reid Barber <[email protected]>

rspbot · 2025-02-04T19:38:04Z

Build successful! 🎉

packages/@react-spectrum/s2/src/TreeView.tsx

packages/@react-stately/layout/src/ListLayout.ts

packages/dev/docs/pages/react-aria/collections.mdx

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

…er-docs # Conflicts: # packages/@react-spectrum/s2/src/TreeView.tsx # packages/react-aria-components/stories/Autocomplete.stories.tsx

rspbot · 2025-02-14T20:37:06Z

Build successful! 🎉

yihuiliao · 2025-02-15T00:17:11Z

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

+
+  return (
+    <Virtualizer layout={layout}>
+      <ListBox aria-label="Favorite animal" items={items} style={{height: 'fit-content'}}>


is it possible to add "orientation="horizontal" to the listbox. just feels weird having to use the up and down arrow keys to navigate through it

great catch!

turns out I had to handle persisted keys in the layout as well. I'd like to move this logic into Virtualizer itself so every layout doesn't have to handle it but will do that separately.

rspbot · 2025-02-15T01:55:31Z

Build successful! 🎉

packages/dev/docs/pages/react-aria/collections.mdx

rspbot · 2025-02-19T18:28:07Z

Build successful! 🎉

rspbot · 2025-02-19T18:28:09Z

## API Changes

react-aria-components

/react-aria-components:UNSTABLE_CollectionRendererContext

-UNSTABLE_CollectionRendererContext {
-  UNTYPED
-}

/react-aria-components:UNSTABLE_DefaultCollectionRenderer

-UNSTABLE_DefaultCollectionRenderer {
-  CollectionBranch: (any) => void
-  CollectionRoot: (any) => void
-}

/react-aria-components:UNSTABLE_TableLayout

-UNSTABLE_TableLayout <T> {
-  constructor: (ListLayoutOptions) => void
-  getContentSize: () => void
-  getDropTargetFromPoint: (number, number, (DropTarget) => boolean) => DropTarget | null
-  getDropTargetLayoutInfo: (ItemDropTarget) => LayoutInfo
-  getItemRect: (Key) => Rect | null
-  getLayoutInfo: (Key) => void
-  getVisibleLayoutInfos: (Rect) => void
-  getVisibleRect: () => Rect
-  shouldInvalidate: (Rect, Rect) => boolean
-  update: (InvalidationContext<TableLayoutProps>) => void
-  updateItemSize: (Key, Size) => void
-  useLayoutOptions: () => void
-  virtualizer: Virtualizer<{}, any> | null
-}

/react-aria-components:UNSTABLE_Virtualizer

-UNSTABLE_Virtualizer <O> {
-  children: ReactNode
-  layout: ILayout<O>
-  layoutOptions?: O
-}

/react-aria-components:UNSTABLE_ListLayout

-UNSTABLE_ListLayout <O = any, T> {
-  constructor: (ListLayoutOptions) => void
-  getContentSize: () => void
-  getDropTargetFromPoint: (number, number, (DropTarget) => boolean) => DropTarget | null
-  getDropTargetLayoutInfo: (ItemDropTarget) => LayoutInfo
-  getItemRect: (Key) => Rect | null
-  getLayoutInfo: (Key) => void
-  getVisibleLayoutInfos: (Rect) => void
-  getVisibleRect: () => Rect
-  shouldInvalidate: (Rect, Rect) => boolean
-  update: (InvalidationContext<O>) => void
-  updateItemSize: (Key, Size) => void
-  virtualizer: Virtualizer<{}, any> | null
-}

/react-aria-components:UNSTABLE_GridLayout

-UNSTABLE_GridLayout <O = any, T> {
-  constructor: (GridLayoutOptions) => void
-  getContentSize: () => Size
-  getDropTargetFromPoint: (number, number, (DropTarget) => boolean) => DropTarget
-  getDropTargetLayoutInfo: (ItemDropTarget) => LayoutInfo
-  getItemRect: (Key) => Rect | null
-  getLayoutInfo: (Key) => LayoutInfo | null
-  getVisibleLayoutInfos: (Rect) => Array<LayoutInfo>
-  getVisibleRect: () => Rect
-  shouldInvalidate: (Rect, Rect) => boolean
-  update: () => void
-  updateItemSize: (Key, Size) => boolean
-  virtualizer: Virtualizer<{}, any> | null
-}

/react-aria-components:ListLayoutOptions

 ListLayoutOptions {
-  dropIndicatorThickness?: number
+  dropIndicatorThickness?: number = 2
   estimatedHeadingHeight?: number
   estimatedRowHeight?: number
-  headingHeight?: number
-  loaderHeight?: number
-  rowHeight?: number
+  gap?: number = 0
+  headingHeight?: number = 48
+  loaderHeight?: number = 48
+  padding?: number = 0
+  rowHeight?: number = 48
 }

/react-aria-components:CollectionRendererContext

+CollectionRendererContext {
+  UNTYPED
+}

/react-aria-components:DefaultCollectionRenderer

+DefaultCollectionRenderer {
+  CollectionBranch: (any) => void
+  CollectionRoot: (any) => void
+}

/react-aria-components:TableLayout

+TableLayout <T> {
+  constructor: (ListLayoutOptions) => void
+  getContentSize: () => void
+  getDropTargetFromPoint: (number, number, (DropTarget) => boolean) => DropTarget | null
+  getDropTargetLayoutInfo: (ItemDropTarget) => LayoutInfo
+  getLayoutInfo: (Key) => void
+  getVisibleLayoutInfos: (Rect) => void
+  shouldInvalidate: (Rect, Rect) => boolean
+  update: (InvalidationContext<TableLayoutProps>) => void
+  updateItemSize: (Key, Size) => void
+  useLayoutOptions: () => void
+  virtualizer: Virtualizer<{}, any> | null
+}

/react-aria-components:Virtualizer

+Virtualizer <O> {
+  children: ReactNode
+  layout: ILayout<O>
+  layoutOptions?: O
+}

/react-aria-components:ListLayout

+ListLayout <O = any, T> {
+  constructor: (ListLayoutOptions) => void
+  getContentSize: () => void
+  getDropTargetFromPoint: (number, number, (DropTarget) => boolean) => DropTarget | null
+  getDropTargetLayoutInfo: (ItemDropTarget) => LayoutInfo
+  getLayoutInfo: (Key) => void
+  getVisibleLayoutInfos: (Rect) => void
+  shouldInvalidate: (Rect, Rect) => boolean
+  update: (InvalidationContext<O>) => void
+  updateItemSize: (Key, Size) => void
+  virtualizer: Virtualizer<{}, any> | null
+}

/react-aria-components:GridLayout

+GridLayout <O = any, T> {
+  constructor: (GridLayoutOptions) => void
+  getContentSize: () => Size
+  getDropTargetFromPoint: (number, number, (DropTarget) => boolean) => DropTarget
+  getDropTargetLayoutInfo: (ItemDropTarget) => LayoutInfo
+  getLayoutInfo: (Key) => LayoutInfo | null
+  getVisibleLayoutInfos: (Rect) => Array<LayoutInfo>
+  shouldInvalidate: (Rect, Rect) => boolean
+  update: () => void
+  updateItemSize: (Key, Size) => boolean
+  virtualizer: Virtualizer<{}, any> | null
+}

/react-aria-components:Layout

+Layout <O = any, T extends {} = Node<any>> {
+  getContentSize: () => Size
+  getDropTargetLayoutInfo: (ItemDropTarget) => LayoutInfo
+  getLayoutInfo: (Key) => LayoutInfo | null
+  getVisibleLayoutInfos: (Rect) => Array<LayoutInfo>
+  shouldInvalidate: (Rect, Rect) => boolean
+  update: (InvalidationContext<O>) => void
+  updateItemSize: (Key, Size) => boolean
+  virtualizer: Virtualizer<{}, any> | null
+}

/react-aria-components:LayoutInfo

+LayoutInfo {
+  allowOverflow: boolean = false
+  constructor: (string, Key, Rect) => void
+  content: any | null
+  copy: () => LayoutInfo
+  estimatedSize: boolean = false
+  isSticky: boolean = false
+  key: Key
+  opacity: number = 1
+  parentKey: Key | null
+  rect: Rect
+  transform: string | null
+  type: string
+  zIndex: number
+}

/react-aria-components:Size

+Size {
+  area: any
+  constructor: (any, any) => void
+  copy: () => Size
+  equals: (Size) => boolean
+  height: number
+  width: number
+}

/react-aria-components:Rect

+Rect {
+  area: number
+  bottomLeft: Point
+  bottomRight: Point
+  constructor: (any, any, any, any) => void
+  containsPoint: (Point) => boolean
+  containsRect: (Rect) => boolean
+  copy: () => Rect
+  equals: (Rect) => void
+  getCornerInRect: (Rect) => RectCorner | null
+  height: number
+  intersection: (Rect) => Rect
+  intersects: (Rect) => boolean
+  maxX: number
+  maxY: number
+  pointEquals: (Point | Rect) => void
+  sizeEquals: (Size | Rect) => void
+  topLeft: Point
+  topRight: Point
+  union: (Rect) => void
+  width: number
+  x: number
+  y: number
+}

/react-aria-components:Point

+Point {
+  constructor: (any, any) => void
+  copy: () => Point
+  equals: (Point) => boolean
+  isOrigin: () => boolean
+  x: number
+  y: number
+}

@react-spectrum/card

/@react-spectrum/card:GalleryLayout

 GalleryLayout <T> {
   _distributeWidths: (any) => void
   _findClosest: (Rect, Rect) => void
   _findClosestLayoutInfo: (Rect, Rect) => void
   buildCollection: () => void
   collection: GridCollection<T>
   constructor: (GalleryLayoutOptions) => void
   direction: Direction
   disabledKeys: Set<Key>
   getContentSize: () => void
   getDropTargetLayoutInfo: (ItemDropTarget) => LayoutInfo
   getFirstKey: () => void
-  getItemRect: (Key) => Rect | null
   getKeyAbove: (Key) => void
   getKeyBelow: (Key) => void
   getKeyForSearch: (string, Key) => void
   getKeyLeftOf: (Key) => void
   getKeyPageAbove: (Key) => void
   getKeyPageBelow: (Key) => void
   getKeyRightOf: (Key) => void
   getLastKey: () => void
   getLayoutInfo: (Key) => void
   getVisibleLayoutInfos: (Rect, any) => void
-  getVisibleRect: () => Rect
   isLoading: boolean
   isVisible: (LayoutInfo, Rect, boolean) => void
   itemPadding: number
   layoutType: any
   scale: Scale
   shouldInvalidate: (Rect, Rect) => boolean
   update: (InvalidationContext<CardViewLayoutOptions>) => void
   updateItemSize: (Key, Size) => boolean
   virtualizer: Virtualizer<{}, any> | null
 }

/@react-spectrum/card:GridLayout

 GridLayout <T> {
   _findClosest: (Rect, Rect) => void
   _findClosestLayoutInfo: (Rect, Rect) => void
   buildChild: (Node<T>, number, number) => LayoutInfo
   buildCollection: () => void
   cardOrientation: Orientation
   collection: GridCollection<T>
   constructor: (GridLayoutOptions) => void
   direction: Direction
   disabledKeys: Set<Key>
   getContentSize: () => void
   getDropTargetLayoutInfo: (ItemDropTarget) => LayoutInfo
   getFirstKey: () => void
   getIndexAtPoint: (any, any, any) => void
-  getItemRect: (Key) => Rect | null
   getKeyAbove: (Key) => void
   getKeyBelow: (Key) => void
   getKeyForSearch: (string, Key) => void
   getKeyLeftOf: (Key) => void
   getKeyPageAbove: (Key) => void
   getKeyPageBelow: (Key) => void
   getKeyRightOf: (Key) => void
   getLastKey: () => void
   getLayoutInfo: (Key) => void
   getVisibleLayoutInfos: (Rect, any) => void
-  getVisibleRect: () => Rect
   isLoading: boolean
   isVisible: (LayoutInfo, Rect, boolean) => void
   itemPadding: number
   layoutType: any
   scale: Scale
   shouldInvalidate: (Rect, Rect) => boolean
   update: (InvalidationContext<CardViewLayoutOptions>) => void
   updateItemSize: (Key, Size) => boolean
   virtualizer: Virtualizer<{}, any> | null
 }

/@react-spectrum/card:WaterfallLayout

 WaterfallLayout <T> {
   _findClosest: (Rect, Rect) => void
   _findClosestLayoutInfo: (Rect, Rect) => void
   buildCollection: (InvalidationContext) => void
   collection: GridCollection<T>
   constructor: (WaterfallLayoutOptions) => void
   direction: Direction
   disabledKeys: Set<Key>
   getClosestLeft: (Key) => void
   getClosestRight: (Key) => void
   getContentSize: () => void
   getDropTargetLayoutInfo: (ItemDropTarget) => LayoutInfo
   getFirstKey: () => void
-  getItemRect: (Key) => Rect | null
   getKeyAbove: (Key) => void
   getKeyBelow: (Key) => void
   getKeyForSearch: (string, Key) => void
   getKeyLeftOf: (Key) => void
   getKeyPageAbove: (Key) => void
   getKeyPageBelow: (Key) => void
   getKeyRightOf: (Key) => void
   getLastKey: () => void
   getLayoutInfo: (Key) => void
   getNextColumnIndex: (any) => void
   getVisibleLayoutInfos: (Rect, any) => void
-  getVisibleRect: () => Rect
   isLoading: boolean
   isVisible: (LayoutInfo, Rect, boolean) => void
   layoutType: any
   margin: number
   shouldInvalidate: (Rect, Rect) => boolean
   update: (InvalidationContext<CardViewLayoutOptions>) => void
   updateItemSize: (Key, Size) => void
   virtualizer: Virtualizer<{}, any> | null
 }

@react-stately/layout

/@react-stately/layout:ListLayoutOptions

 ListLayoutOptions {
-  dropIndicatorThickness?: number
+  dropIndicatorThickness?: number = 2
   estimatedHeadingHeight?: number
   estimatedRowHeight?: number
-  headingHeight?: number
-  loaderHeight?: number
-  rowHeight?: number
+  gap?: number = 0
+  headingHeight?: number = 48
+  loaderHeight?: number = 48
+  padding?: number = 0
+  rowHeight?: number = 48
 }

/@react-stately/layout:GridLayout

 GridLayout <O = any, T> {
   constructor: (GridLayoutOptions) => void
   getContentSize: () => Size
   getDropTargetFromPoint: (number, number, (DropTarget) => boolean) => DropTarget
   getDropTargetLayoutInfo: (ItemDropTarget) => LayoutInfo
-  getItemRect: (Key) => Rect | null
   getLayoutInfo: (Key) => LayoutInfo | null
   getVisibleLayoutInfos: (Rect) => Array<LayoutInfo>
-  getVisibleRect: () => Rect
   shouldInvalidate: (Rect, Rect) => boolean
   update: () => void
   updateItemSize: (Key, Size) => boolean
   virtualizer: Virtualizer<{}, any> | null

/@react-stately/layout:ListLayout

 ListLayout <O = any, T> {
   constructor: (ListLayoutOptions) => void
   getContentSize: () => void
   getDropTargetFromPoint: (number, number, (DropTarget) => boolean) => DropTarget | null
   getDropTargetLayoutInfo: (ItemDropTarget) => LayoutInfo
-  getItemRect: (Key) => Rect | null
   getLayoutInfo: (Key) => void
   getVisibleLayoutInfos: (Rect) => void
-  getVisibleRect: () => Rect
   shouldInvalidate: (Rect, Rect) => boolean
   update: (InvalidationContext<O>) => void
   updateItemSize: (Key, Size) => void
   virtualizer: Virtualizer<{}, any> | null

/@react-stately/layout:TableLayout

 TableLayout <O extends TableLayoutProps = TableLayoutProps, T> {
   constructor: (ListLayoutOptions) => void
   getContentSize: () => void
   getDropTargetFromPoint: (number, number, (DropTarget) => boolean) => DropTarget | null
   getDropTargetLayoutInfo: (ItemDropTarget) => LayoutInfo
-  getItemRect: (Key) => Rect | null
   getLayoutInfo: (Key) => void
   getVisibleLayoutInfos: (Rect) => void
-  getVisibleRect: () => Rect
   shouldInvalidate: (Rect, Rect) => boolean
   update: (InvalidationContext<TableLayoutProps>) => void
   updateItemSize: (Key, Size) => void
   virtualizer: Virtualizer<{}, any> | null

@react-stately/virtualizer

/@react-stately/virtualizer:Layout

-Layout <O = any, T extends {}> {
+Layout <O = any, T extends {} = Node<any>> {
   getContentSize: () => Size
   getDropTargetLayoutInfo: (ItemDropTarget) => LayoutInfo
-  getItemRect: (Key) => Rect | null
   getLayoutInfo: (Key) => LayoutInfo | null
   getVisibleLayoutInfos: (Rect) => Array<LayoutInfo>
-  getVisibleRect: () => Rect
   shouldInvalidate: (Rect, Rect) => boolean
   update: (InvalidationContext<O>) => void
   updateItemSize: (Key, Size) => boolean
   virtualizer: Virtualizer<{}, any> | null

/@react-stately/virtualizer:LayoutInfo

 LayoutInfo {
   allowOverflow: boolean = false
   constructor: (string, Key, Rect) => void
   content: any | null
   copy: () => LayoutInfo
-  estimatedSize: boolean
-  isSticky: boolean
+  estimatedSize: boolean = false
+  isSticky: boolean = false
   key: Key
-  opacity: number
+  opacity: number = 1
   parentKey: Key | null
   rect: Rect
   transform: string | null
   type: string
 }

devongovett added 8 commits January 29, 2025 16:57

wip: Virtualizer docs

910238e

Merge branch 'main' of github.com:adobe/react-spectrum into virtualiz…

91bb394

…er-docs

Remove UNSTABLE prefix

ca0430f

Update JS docs

6636a35

update content

2de1b12

Revert useListBox docs for now

8ccf27f

Fix TS

460e195

lint

baf4c2a

slight text update

e48de37

reidbarber requested changes Feb 4, 2025

View reviewed changes

packages/react-aria-components/src/Virtualizer.tsx Outdated Show resolved Hide resolved

Update packages/react-aria-components/src/Virtualizer.tsx

4dc8819

Co-authored-by: Reid Barber <[email protected]>

snowystinger reviewed Feb 4, 2025

View reviewed changes

devongovett mentioned this pull request Feb 6, 2025

feat: Add WaterfallLayout to RAC, and update GridLayout #7729

Merged

devongovett added the release label Feb 13, 2025

devongovett added 4 commits February 14, 2025 12:06

review comments

d0bc7a5

Remove UNSTABLE prefix from CollectionRendererContext

363633b

Merge branch 'main' of github.com:adobe/react-spectrum into virtualiz…

a9673ce

…er-docs # Conflicts: # packages/@react-spectrum/s2/src/TreeView.tsx # packages/react-aria-components/stories/Autocomplete.stories.tsx

Use gap in TreeView

c5a3cec

reidbarber previously approved these changes Feb 14, 2025

View reviewed changes

yihuiliao reviewed Feb 15, 2025

View reviewed changes

fix keyboard navigation of custom layout example

97a0420

devongovett dismissed reidbarber’s stale review via 97a0420 February 15, 2025 01:46

snowystinger reviewed Feb 17, 2025

View reviewed changes

packages/dev/docs/pages/react-aria/collections.mdx Show resolved Hide resolved

Merge branch 'main' into virtualizer-docs

a224ae2

snowystinger approved these changes Feb 19, 2025

View reviewed changes

yihuiliao approved these changes Feb 19, 2025

View reviewed changes

devongovett added this pull request to the merge queue Feb 20, 2025

Merged via the queue into main with commit ec9ae73 Feb 20, 2025
30 checks passed

devongovett deleted the virtualizer-docs branch February 20, 2025 01:32

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Add Virtualizer docs #7700

docs: Add Virtualizer docs #7700

devongovett commented Feb 1, 2025 •

edited

Loading

rspbot commented Feb 1, 2025

rspbot commented Feb 1, 2025

reidbarber left a comment

rspbot commented Feb 4, 2025

rspbot commented Feb 14, 2025

yihuiliao Feb 15, 2025

devongovett Feb 15, 2025

devongovett Feb 15, 2025

rspbot commented Feb 15, 2025

rspbot commented Feb 19, 2025

rspbot commented Feb 19, 2025

docs: Add Virtualizer docs #7700

docs: Add Virtualizer docs #7700

Conversation

devongovett commented Feb 1, 2025 • edited Loading

rspbot commented Feb 1, 2025

rspbot commented Feb 1, 2025

reidbarber left a comment

Choose a reason for hiding this comment

rspbot commented Feb 4, 2025

rspbot commented Feb 14, 2025

yihuiliao Feb 15, 2025

Choose a reason for hiding this comment

devongovett Feb 15, 2025

Choose a reason for hiding this comment

devongovett Feb 15, 2025

Choose a reason for hiding this comment

rspbot commented Feb 15, 2025

rspbot commented Feb 19, 2025

rspbot commented Feb 19, 2025

react-aria-components

/react-aria-components:UNSTABLE_CollectionRendererContext

/react-aria-components:UNSTABLE_DefaultCollectionRenderer

/react-aria-components:UNSTABLE_TableLayout

/react-aria-components:UNSTABLE_Virtualizer

/react-aria-components:UNSTABLE_ListLayout

/react-aria-components:UNSTABLE_GridLayout

/react-aria-components:ListLayoutOptions

/react-aria-components:CollectionRendererContext

/react-aria-components:DefaultCollectionRenderer

/react-aria-components:TableLayout

/react-aria-components:Virtualizer

/react-aria-components:ListLayout

/react-aria-components:GridLayout

/react-aria-components:Layout

/react-aria-components:LayoutInfo

/react-aria-components:Size

/react-aria-components:Rect

/react-aria-components:Point

@react-spectrum/card

/@react-spectrum/card:GalleryLayout

/@react-spectrum/card:GridLayout

/@react-spectrum/card:WaterfallLayout

@react-stately/layout

/@react-stately/layout:ListLayoutOptions

/@react-stately/layout:GridLayout

/@react-stately/layout:ListLayout

/@react-stately/layout:TableLayout

@react-stately/virtualizer

/@react-stately/virtualizer:Layout

/@react-stately/virtualizer:LayoutInfo

devongovett commented Feb 1, 2025 •

edited

Loading