react-window 2.4.0 → 2.5.0

package/dist/react-window.d.ts

@@ -41,7 +41,7 @@ export declare function getScrollbarSize(recalculate?: boolean, ownerDocument?:
  * ℹ️ Unlike `List` rows, `Grid` cell sizes must be known ahead of time.
  * Either static sizes or something that can be derived (from the data in `CellProps`) without rendering.
  */
-export declare function Grid<CellProps extends object, TagName extends TagNames = "div">({ cellComponent: CellComponentProp, cellProps: cellPropsUnstable, children, className, columnCount, columnKey, columnWidth, defaultHeight, defaultScrollLeft, defaultScrollTop, defaultWidth, dir, gridRef, onCellsRendered, onResize, overscanCount, rowCount, rowHeight, rowKey, style, tagName, ...rest }: GridProps<CellProps, TagName>): ReactElement;
+export declare function Grid<CellProps extends object, TagName extends TagNames = "div">({ cellComponent: CellComponentProp, cellProps: cellPropsUnstable, children, className, columnCount, columnKey, columnWidth, defaultHeight, defaultScrollLeft, defaultScrollTop, defaultWidth, dir, gridRef, onCellsRendered, onResize, overscanCount, rowCount, rowHeight, rowKey, scrollElement, style, tagName, ...rest }: GridProps<CellProps, TagName>): ReactElement;
 
 /**
  * Ref used to interact with this component's imperative API.
@@ -57,6 +57,8 @@ export declare interface GridImperativeAPI {
     get element(): HTMLDivElement | null;
     /**
      * Scrolls the grid so that the specified row and column are visible.
+     * Like the browser's `scrollIntoView`, items are aligned within the CSS `scroll-padding` of the element being scrolled
+     * (e.g. `scroll-padding-top` can leave room for a sticky header).
      *
      * @param behavior Determines whether scrolling is instant or animates smoothly
      * @param columnAlign Determines the horizontal alignment of the element within the grid
@@ -75,6 +77,8 @@ export declare interface GridImperativeAPI {
     }) => void;
     /**
      * Scrolls the grid so that the specified column is visible.
+     * Like the browser's `scrollIntoView`, items are aligned within the CSS `scroll-padding` of the element being scrolled
+     * (e.g. `scroll-padding-top` can leave room for a sticky header).
      *
      * @param align Determines the horizontal alignment of the element within the grid
      * @param behavior Determines whether scrolling is instant or animates smoothly
@@ -89,6 +93,8 @@ export declare interface GridImperativeAPI {
     }) => void;
     /**
      * Scrolls the grid so that the specified row is visible.
+     * Like the browser's `scrollIntoView`, items are aligned within the CSS `scroll-padding` of the element being scrolled
+     * (e.g. `scroll-padding-top` can leave room for a sticky header).
      *
      * @param align Determines the vertical alignment of the element within the grid
      * @param behavior Determines whether scrolling is instant or animates smoothly
@@ -225,6 +231,8 @@ export declare type GridProps<CellProps extends object, TagName extends TagNames
         get element(): HTMLDivElement | null;
         /**
          * Scrolls the grid so that the specified row and column are visible.
+         * Like the browser's `scrollIntoView`, items are aligned within the CSS `scroll-padding` of the element being scrolled
+         * (e.g. `scroll-padding-top` can leave room for a sticky header).
          *
          * @param behavior Determines whether scrolling is instant or animates smoothly
          * @param columnAlign Determines the horizontal alignment of the element within the grid
@@ -243,6 +251,8 @@ export declare type GridProps<CellProps extends object, TagName extends TagNames
         }): void;
         /**
          * Scrolls the grid so that the specified column is visible.
+         * Like the browser's `scrollIntoView`, items are aligned within the CSS `scroll-padding` of the element being scrolled
+         * (e.g. `scroll-padding-top` can leave room for a sticky header).
          *
          * @param align Determines the horizontal alignment of the element within the grid
          * @param behavior Determines whether scrolling is instant or animates smoothly
@@ -257,6 +267,8 @@ export declare type GridProps<CellProps extends object, TagName extends TagNames
         }): void;
         /**
          * Scrolls the grid so that the specified row is visible.
+         * Like the browser's `scrollIntoView`, items are aligned within the CSS `scroll-padding` of the element being scrolled
+         * (e.g. `scroll-padding-top` can leave room for a sticky header).
          *
          * @param align Determines the vertical alignment of the element within the grid
          * @param behavior Determines whether scrolling is instant or animates smoothly
@@ -328,6 +340,27 @@ export declare type GridProps<CellProps extends object, TagName extends TagNames
         data: CellProps;
         rowIndex: number;
     }) => React.Key;
+    /**
+     * Element that scrolls the grid, for grids that scroll along with other content (e.g. the page):
+     * - "window" to scroll with the page
+     * - an ancestor element that scrolls (e.g. stored with a `useState` ref callback); `null` until it has mounted
+     *
+     * The grid renders at its full height and only renders the rows (and columns) visible within the scroll element's viewport.
+     * Its position within the scroll element is measured whenever it renders, scrolls, or resizes,
+     * and whenever content before it is resized, inserted, or removed (e.g. an image loading above the grid).
+     * - columns scroll with the scroll element too if the grid is as wide as its content (e.g. `style={{ width: "max-content" }}`);
+     *   otherwise the grid fills the width of its parent and its columns scroll within it
+     * - `scrollToCell`, `scrollToColumn` and `scrollToRow` scroll whichever element scrolls each axis
+     * - `defaultHeight` and `defaultWidth` are used as the viewport size until the scroll element has been measured (e.g. during server rendering)
+     * - percentage row heights and column widths are relative to the scroll element's viewport
+     * - `defaultScrollLeft` and `defaultScrollTop` are ignored
+     *
+     * ℹ️ While the scroll element is `null`, the grid renders the first rows (as it does during server rendering).
+     *
+     * ⚠️ The grid's `onScroll` handler is only called when the grid scrolls its own columns;
+     * listen to the scroll element's "scroll" events instead (or use the `useIsScrolling` hook).
+     */
+    scrollElement?: "window" | HTMLElement | null;
     /**
      * Optional CSS properties.
      * The grid of cells will fill the height and width defined by this style.
@@ -345,7 +378,7 @@ export declare type GridProps<CellProps extends object, TagName extends TagNames
 /**
  * Renders data with many rows.
  */
-export declare function List<RowProps extends object, TagName extends TagNames = "div">({ children, className, defaultHeight, defaultScrollOffset, listRef, onResize, onRowsRendered, overscanCount, rowComponent: RowComponentProp, rowCount, rowHeight: rowHeightProp, rowKey, rowProps: rowPropsUnstable, tagName, style, ...rest }: ListProps<RowProps, TagName>): ReactElement;
+export declare function List<RowProps extends object, TagName extends TagNames = "div">({ children, className, defaultHeight, defaultScrollOffset, listRef, onResize, onRowsRendered, overscanCount, rowComponent: RowComponentProp, rowCount, rowHeight: rowHeightProp, rowKey, rowProps: rowPropsUnstable, scrollElement, tagName, style, ...rest }: ListProps<RowProps, TagName>): ReactElement;
 
 /**
  * Imperative List API.
@@ -359,6 +392,8 @@ export declare interface ListImperativeAPI {
     get element(): HTMLDivElement | null;
     /**
      * Scrolls the list so that the specified row is visible.
+     * Like the browser's `scrollIntoView`, items are aligned within the CSS `scroll-padding` of the element being scrolled
+     * (e.g. `scroll-padding-top` can leave room for a sticky header).
      *
      * Dynamic row heights are measured after rendering;
      * Content that resizes later may require another scrollToRow call.
@@ -422,6 +457,8 @@ export declare type ListProps<RowProps extends object, TagName extends TagNames
         get element(): HTMLDivElement | null;
         /**
          * Scrolls the list so that the specified row is visible.
+         * Like the browser's `scrollIntoView`, items are aligned within the CSS `scroll-padding` of the element being scrolled
+         * (e.g. `scroll-padding-top` can leave room for a sticky header).
          *
          * Dynamic row heights are measured after rendering;
          * Content that resizes later may require another scrollToRow call.
@@ -520,6 +557,25 @@ export declare type ListProps<RowProps extends object, TagName extends TagNames
      * ⚠️ This object must not contain `ariaAttributes`, `index`, or `style` props.
      */
     rowProps: ExcludeForbiddenKeys_2<RowProps>;
+    /**
+     * Element that scrolls the list, for lists that scroll along with other content (e.g. the page):
+     * - "window" to scroll with the page
+     * - an ancestor element that scrolls (e.g. stored with a `useState` ref callback); `null` until it has mounted
+     *
+     * The list renders at its full height and only renders the rows visible within the scroll element's viewport.
+     * Its position within the scroll element is measured whenever it renders, scrolls, or resizes,
+     * and whenever content before it is resized, inserted, or removed (e.g. an image loading above the list).
+     * - `scrollToRow` scrolls the scroll element
+     * - `defaultHeight` is used as the viewport height until the scroll element has been measured (e.g. during server rendering)
+     * - percentage row heights are relative to the scroll element's viewport height
+     * - `defaultScrollOffset` is ignored
+     *
+     * ℹ️ While the scroll element is `null`, the list renders the first rows (as it does during server rendering).
+     *
+     * ⚠️ The list itself doesn't scroll, so its `onScroll` handler isn't called;
+     * listen to the scroll element's "scroll" events instead (or use the `useIsScrolling` hook).
+     */
+    scrollElement?: "window" | HTMLElement | null;
     /**
      * Optional CSS properties.
      * The list of rows will fill the height defined by this style.
@@ -574,6 +630,29 @@ export declare const useGridCallbackRef: typeof useState<GridImperativeAPI | nul
  */
 export declare const useGridRef: typeof useRef<GridImperativeAPI>;
 
+/**
+ * Tracks whether an element (or the window) is currently scrolling,
+ * e.g. to render simplified content in place of rows that are expensive to render.
+ *
+ * Pass the element that scrolls:
+ * - a list or grid's own element (e.g. from `useListCallbackRef`)
+ * - "window" or the scroll element, for lists and grids that use the `scrollElement` prop
+ *
+ * Scrolling ends when the browser fires a "scrollend" event or,
+ * in browsers that don't support that event, after no scroll events have been received for `delay` milliseconds.
+ *
+ * ℹ️ Scrolling that starts and ends before React renders (e.g. an instant scroll) may not change this value.
+ *
+ * ⚠️ Changing this value re-renders any rows it is passed to (e.g. via `rowProps`) when scrolling starts and when it ends.
+ */
+export declare function useIsScrolling(target: "window" | HTMLElement | null | undefined, { delay }?: {
+    /**
+     * Milliseconds without scroll events after which scrolling is considered to have ended
+     * (only used by browsers that don't support the "scrollend" event); defaults to 150.
+     */
+    delay?: number;
+}): boolean;
+
 /**
  * Convenience hook to return a properly typed ref callback for the List component.
  *
@@ -586,4 +665,128 @@ export declare const useListCallbackRef: typeof useState<ListImperativeAPI | nul
  */
 export declare const useListRef: typeof useRef<ListImperativeAPI>;
 
+/**
+ * Calculates which items to render, and where, for custom (headless) virtualized content
+ * (e.g. a `<table>` or a custom layout).
+ *
+ * The returned items are positioned relative to the start of the element's content;
+ * how they are rendered (e.g. absolute positioning or spacer elements) is up to the caller.
+ */
+export declare function useVirtualizer({ count, defaultScrollOffset, defaultSize, dir, direction, element, itemSize: itemSizeOption, onItemsRendered, overscanCount, scrollElement }: VirtualizerOptions): Virtualizer;
+
+export declare type VirtualItem = {
+    /**
+     * Index of the item.
+     */
+    index: number;
+    /**
+     * Offset (in pixels) of the item from the start of the element's content.
+     */
+    offset: number;
+    /**
+     * Size (in pixels) of the item; an estimate for dynamic sizes that have not yet been measured.
+     */
+    size: number;
+};
+
+export declare type Virtualizer = {
+    /**
+     * Items to render (including overscan).
+     */
+    items: VirtualItem[];
+    /**
+     * Ref callback for rendered items, required for items with dynamic sizes (see `itemSize`).
+     */
+    measureElement: (element: Element | null) => void;
+    /**
+     * Scrolls the element (or scroll element) so that the specified item is visible.
+     * Like the browser's `scrollIntoView`, items are aligned within the CSS `scroll-padding` of the element being scrolled
+     * (e.g. `scroll-padding-top` can leave room for a sticky header).
+     *
+     * @throws RangeError if an invalid index is provided
+     */
+    scrollToIndex: (options: {
+        align?: Align;
+        behavior?: ScrollBehavior;
+        index: number;
+    }) => void;
+    /**
+     * Total size (in pixels) of all items; an estimate for dynamic sizes that have not yet been measured.
+     */
+    totalSize: number;
+    /**
+     * Range of items within the visible area (excluding overscan).
+     */
+    visibleRange: {
+        startIndex: number;
+        stopIndex: number;
+    };
+};
+
+export declare type VirtualizerOptions = {
+    /**
+     * Number of items.
+     */
+    count: number;
+    /**
+     * Initial scroll offset (in pixels), applied once when the element first mounts with at least one item.
+     *
+     * ℹ️ Ignored when a `scrollElement` is specified.
+     */
+    defaultScrollOffset?: number;
+    /**
+     * Size (in pixels) of the viewport before it has been measured (e.g. during server rendering);
+     * this determines how many items are initially rendered.
+     */
+    defaultSize?: number;
+    /**
+     * Direction of horizontal content; detected from the element (or its ancestors) by default.
+     */
+    dir?: "ltr" | "rtl";
+    /**
+     * Direction that items are laid out in; defaults to "vertical".
+     */
+    direction?: "horizontal" | "vertical";
+    /**
+     * Element that scrolls the items or, if a `scrollElement` is specified, the element that contains the items.
+     *
+     * ℹ️ Item offsets are relative to the start of this element's content.
+     */
+    element: HTMLElement | null;
+    /**
+     * Item size; the following formats are supported:
+     * - number of pixels (number)
+     * - percentage of the viewport's size (string)
+     * - function that returns the item size (in pixels) given an index
+     * - dynamic row height cache returned by the `useDynamicRowHeight` hook (vertical only);
+     *   rendered items must be passed to `measureElement` and specify a `data-index` attribute
+     *
+     * ℹ️ Sizes are cached until the value of this option changes;
+     * memoize functions (e.g. with `useCallback`) and only change them when sizes change.
+     */
+    itemSize: number | string | ((index: number) => number) | DynamicRowHeight;
+    /**
+     * Callback notified when the range of visible (or rendered) items changes.
+     */
+    onItemsRendered?: (visibleItems: {
+        startIndex: number;
+        stopIndex: number;
+    }, allItems: {
+        startIndex: number;
+        stopIndex: number;
+    }) => void;
+    /**
+     * How many additional items to render outside of the visible area; defaults to 3.
+     */
+    overscanCount?: number;
+    /**
+     * Element that scrolls the items, for items that scroll along with other content (e.g. the page):
+     * - "window" to scroll with the page
+     * - an ancestor element that scrolls; `null` until it has mounted
+     *
+     * See the `scrollElement` prop of `List` for more information.
+     */
+    scrollElement?: "window" | HTMLElement | null;
+};
+
 export { }