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 <reid@reidbarber.com>

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

Build successful! 🎉

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

## API Changes

react-aria-components

/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: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-spectrum/s2

/@react-spectrum/s2:ImageProps

 ImageProps {
   UNSAFE_className?: string
   UNSAFE_style?: CSSProperties
   alt?: string
   crossOrigin?: 'anonymous' | 'use-credentials'
   decoding?: 'async' | 'auto' | 'sync'
-  fetchPriority?: 'high' | 'low' | 'auto'
   group?: ImageGroup
   loading?: 'eager' | 'lazy'
   referrerPolicy?: HTMLAttributeReferrerPolicy
   renderError?: () => ReactNode
   src?: string
   styles?: StyleString
 }

@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
 }

snowystinger · 2025-02-04T20:38:29Z

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

+    return new ListLayout({
      rowHeight: isDetached ? 42 : 40


Suggested change

return new ListLayout({

rowHeight: isDetached ? 42 : 40

return new ListLayout({

rowHeight: 40,

gap: isDetached ? 2 : 0

now that there is a gap property

snowystinger · 2025-02-04T20:39:12Z

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

+   * The gap between items.
+   * @default 0
+   */
+  gap?: number,


maybe an odd question, where does the drop indicator render in relation to the gap? top? bottom? middle?

drop indicator should be centered between the items, regardless of the gap

snowystinger · 2025-02-04T20:56:20Z

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

+
+```tsx
+import type {CollectionRenderer} from 'react-aria-components';
+import {UNSTABLE_CollectionRendererContext as CollectionRendererContext} from 'react-aria-components';


if we're keeping this as unstable, can we put a pre-release badge on the title of the section?

snowystinger · 2025-02-04T21:01:56Z

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

+
+**Note**: ensure that the value passed to `CollectionRendererContext` is memoized so React does not unmount and remount `CollectionRoot` and `CollectionBranch` unnecessarily.
+
+You also need to ensure that any additional DOM elements you add, such as wrappers around the items, are valid within the ARIA pattern that the collection component follows. Use `role="presentation"` for elements added only for styling purposes.


put in an important requirement?

snowystinger · 2025-02-04T21:02:47Z

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

+
+## Layouts
+
+Virtualizer uses <TypeLink links={docs.links} type={docs.exports.Layout} /> objects to determine the position and size of each item, and provide the list of currently visible items. When using a Virtualizer, all items are positioned by the `Layout`, and CSS layout properties such as flexbox and grid do not apply.


Suggested change

Virtualizer uses <TypeLink links={docs.links} type={docs.exports.Layout} /> objects to determine the position and size of each item, and provide the list of currently visible items. When using a Virtualizer, all items are positioned by the `Layout`, and CSS layout properties such as flexbox and grid do not apply.

Virtualizer uses <TypeLink links={docs.links} type={docs.exports.Layout} /> objects to determine the position and size of each item, and provides the list of currently visible items. When using a Virtualizer, all items are positioned by the `Layout`, and CSS layout properties such as flexbox and grid do not apply.

snowystinger · 2025-02-04T21:07:59Z

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

+`GridLayout` supports layout of items in an equal size grid. The items are sized between a minimum and maximum size depending on the width of the container. It supports the following options:
+
+<TypeContext.Provider value={docs.links}>
+  <InterfaceType {...docs.exports.GridLayoutOptions} />


for some reason, some sizes render as 200 x 200, but others are just Infinity, with no cross dimension

https://reactspectrum.blob.core.windows.net/reactspectrum/4dc8819bc6405886e263049d98a1610aec8adf46/docs/react-aria/Virtualizer.html#gridlayout

snowystinger · 2025-02-04T21:10:26Z

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

+    items.push({id: i, name: `Item ${i}`});
+  }
+
+  return (


Last example needs to have less height on the items so it doesn't vertically scroll

lol, stupid scrollbars 😂

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 <reid@reidbarber.com>

snowystinger reviewed Feb 4, 2025

View reviewed changes

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 4, 2025

snowystinger Feb 4, 2025

snowystinger Feb 4, 2025

devongovett Feb 5, 2025

snowystinger Feb 4, 2025

snowystinger Feb 4, 2025

snowystinger Feb 4, 2025

snowystinger Feb 4, 2025

devongovett Feb 5, 2025

snowystinger Feb 5, 2025

snowystinger Feb 4, 2025

devongovett Feb 5, 2025


		Note: ensure that the value passed to `CollectionRendererContext` is memoized so React does not unmount and remount `CollectionRoot` and `CollectionBranch` unnecessarily.

		You also need to ensure that any additional DOM elements you add, such as wrappers around the items, are valid within the ARIA pattern that the collection component follows. Use `role="presentation"` for elements added only for styling purposes.


		## Layouts

		Virtualizer uses <TypeLink links={docs.links} type={docs.exports.Layout} /> objects to determine the position and size of each item, and provide the list of currently visible items. When using a Virtualizer, all items are positioned by the `Layout`, and CSS layout properties such as flexbox and grid do not apply.

docs: Add Virtualizer docs #7700

Are you sure you want to change the base?

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 4, 2025

react-aria-components

/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: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-spectrum/s2

/@react-spectrum/s2:ImageProps

@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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

devongovett commented Feb 1, 2025 •

edited

Loading