Add initialScroll prop

src/core/store.ts

@@ -13,6 +13,7 @@ import {
 import { isIOSWebKit } from "./environment";
 import type {
   CacheSnapshot,
+  InitialScrollProp,
   InternalCacheSnapshot,
   ItemResize,
   ItemsRange,
@@ -141,6 +142,7 @@ export const createVirtualStore = (
   ssrCount: number = 0,
   cacheSnapshot?: CacheSnapshot | undefined,
   shouldAutoEstimateItemSize: boolean = false,
+  initialScroll?: InitialScrollProp | undefined,
   startSpacerSize: number = 0
 ): VirtualStore => {
   let isSSR = !!ssrCount;
@@ -189,6 +191,11 @@ export const createVirtualStore = (
     }
   };
 
+  if (initialScroll) {
+    scrollOffset =
+      initialScroll.offset ?? getItemOffset(initialScroll.index || 0);
+  }
+
   return {
     _getStateVersion() {
       return stateVersion;

src/core/types.ts

@@ -42,3 +42,11 @@ export interface ScrollToIndexOpts {
    */
   offset?: number;
 }
+
+export interface InitialScrollProp extends ScrollToIndexOpts {
+  /**
+   * Index of item.
+   * @defaultValue 0
+   */
+  index?: number;
+}

src/index.ts

@@ -5,5 +5,6 @@ export type {
   CacheSnapshot,
   ScrollToIndexAlign,
   ScrollToIndexOpts,
+  InitialScrollProp,
 } from "./core/types";
 export * from "./react";

src/react/VList.tsx

@@ -23,6 +23,7 @@ export interface VListProps
       | "itemSize"
       | "shift"
       | "horizontal"
+      | "initialScroll"
       | "cache"
       | "ssrCount"
       | "item"
@@ -52,6 +53,7 @@ export const VList = forwardRef<VListHandle, VListProps>(
       shift,
       horizontal,
       reverse,
+      initialScroll,
       cache,
       ssrCount,
       item,
@@ -76,6 +78,7 @@ export const VList = forwardRef<VListHandle, VListProps>(
         itemSize={itemSize}
         shift={shift}
         horizontal={horizontal}
+        initialScroll={initialScroll}
         cache={cache}
         ssrCount={ssrCount}
         item={item}

src/react/Virtualizer.tsx

@@ -24,7 +24,11 @@
 import { useLatestRef } from "./useLatestRef";
 import { createResizer } from "../core/resizer";
 import { ListItem } from "./ListItem";
-import { CacheSnapshot, ScrollToIndexOpts } from "../core/types";
+import {
+  CacheSnapshot,
+  InitialScrollProp,
+  ScrollToIndexOpts,
+} from "../core/types";
 import { flushSync } from "react-dom";
 import { useRerender } from "./useRerender";
 import { useChildren } from "./useChildren";
@@ -112,6 +116,10 @@
    * If true, rendered as a horizontally scrollable list. Otherwise rendered as a vertically scrollable list.
    */
   horizontal?: boolean;
+  /**
+   * TODO
+   */
+  initialScroll?: InitialScrollProp;
   /**
    * You can restore cache by passing a {@link CacheSnapshot} on mount. This is useful when you want to restore scroll position after navigation. The snapshot can be obtained from {@link VirtualizerHandle.cache}.
    *
@@ -177,6 +185,7 @@
       itemSize,
       shift,
       horizontal: horizontalProp,
+      initialScroll,
       cache,
       startMargin,
       ssrCount,
@@ -208,6 +217,7 @@
         ssrCount,
         cache,
         !itemSize,
+        initialScroll,
         startMargin
       );
       return [
@@ -284,6 +294,9 @@
       const assignScrollableElement = (e: HTMLElement) => {
         resizer._observeRoot(e);
         scroller._observe(e);
+        if (initialScroll) {
+          scroller._scrollToIndex(initialScroll.index || 0, initialScroll);
+        }
       };
       if (scrollRef) {
         // parent's ref doesn't exist when useLayoutEffect is called
@@ -309,7 +322,7 @@
       if (!onRangeChangeProp) return;
 
       onRangeChangeProp(startIndex, endIndex);
     }, [startIndex, endIndex]);
 
     useImperativeHandle(
       ref,
@@ -333,7 +346,7 @@
           scrollBy: scroller._scrollBy,
         };
       },
       []
     );
 
     for (let i = overscanedRangeStart, j = overscanedRangeEnd; i <= j; i++) {

src/vue/Virtualizer.tsx

@@ -118,6 +118,7 @@ export const Virtualizer = /*#__PURE__*/ defineComponent({
       props.ssrCount,
       undefined,
       !props.itemSize,
+      undefined,
       props.startMargin
     );
     const resizer = createResizer(store, isHorizontal);

stories/react/advanced/Keep offscreen items.stories.tsx

@@ -152,12 +152,6 @@ export const SelectedIndex: StoryObj = {
       isPrepend.current = false;
     });
 
-    useEffect(() => {
-      if (!ref.current) return;
-
-      ref.current.scrollToIndex(items.length - 1, { align: "end" });
-    }, []);
-
     const toggleEditing = useCallback((itemId: number) => {
       setEditingItemId((currentValue) =>
         itemId === currentValue ? null : itemId
@@ -185,6 +179,7 @@ export const SelectedIndex: StoryObj = {
           ref={ref}
           style={{ flex: 1 }}
           reverse
+          initialScroll={{ index: items.length - 1, align: "end" }}
           keepMounted={
             editingItemId
               ? [items.findIndex((item) => item.id === editingItemId)]

stories/react/basics/VList.stories.tsx

@@ -106,12 +106,8 @@ export const PaddingAndMargin: StoryObj = {
 
 export const Reverse: StoryObj = {
   render: () => {
-    const ref = useRef<VListHandle>(null);
-    useEffect(() => {
-      ref.current?.scrollToIndex(999);
-    }, []);
     return (
-      <VList ref={ref} style={{ height: "100vh" }} reverse>
+      <VList style={{ height: "100vh" }} reverse initialScroll={{ index: 999 }}>
         {createRows(1000)}
       </VList>
     );
@@ -402,10 +398,6 @@ const RestorableList = ({ id }: { id: string }) => {
     if (!ref.current) return;
     const handle = ref.current;
 
-    if (offset) {
-      handle.scrollTo(offset);
-    }
-
     return () => {
       sessionStorage.setItem(
         cacheKey,
@@ -415,7 +407,12 @@ const RestorableList = ({ id }: { id: string }) => {
   }, []);
 
   return (
-    <VList ref={ref} cache={cache} style={{ height: "100vh" }}>
+    <VList
+      ref={ref}
+      cache={cache}
+      initialScroll={{ offset }}
+      style={{ height: "100vh" }}
+    >
       {createRows(1000)}
     </VList>
   );