Virtua Restoration

It is a wrapper component that facilitates virtual listing with the virtua library by storing scroll position and cache information in React applications.

🧪 Demo

https://virtua-restoration.vercel.app

✨ Features

• Maintains scroll position when doing virtual listing.
• Provides cache management with sessionStorage, localStorage or custom (e.g. Zustand).
• Works with the virtua library.
• Prevents scroll and cache loss on route transitions or page refreshes.

📦 Installation

pnpm add virtua virtua-restoration
# or
npm install virtua virtua-restoration
# or
yarn add virtua virtua-restoration

📚 Peer Dependencies

Package	Version
react	>=19.0.0
react-dom	>=19.0.0
virtua	>=0.41.5

🚀 Usage

Basic Usage (with sessionStorage) | Demo

import { WindowVirtualizedList } from 'virtua-restoration'

export default function Example() {
  return (
    <WindowVirtualizedList cacheKey="feed">
      {[...Array(200)].map((_, i) => (
        <div key={i} style={{ height: 80, borderBottom: '1px solid #ddd' }}>
          Row {i}
        </div>
      ))}
    </WindowVirtualizedList>
  )
}

Use with localStorage | Demo

import { WindowVirtualizedList } from 'virtua-restoration'

export default function Example() {
  return (
    <WindowVirtualizedList cacheKey="feed" cacheSource="localStorage">
      {[...Array(200)].map((_, i) => (
        <div key={i} style={{ height: 80, borderBottom: '1px solid #ddd' }}>
          Row {i}
        </div>
      ))}
    </WindowVirtualizedList>
  )
}

Usage with zustand | Demo

// store/virtualListStore.ts
import { create } from 'zustand'
import { CacheSnapshot } from 'virtua'

interface VirtualListState {
  cacheMap: Record<string, [number, CacheSnapshot]>
  get: (key: string) => [number, CacheSnapshot] | undefined
  set: (key: string, data: [number, CacheSnapshot]) => void
}

export const useVirtualListStore = create<VirtualListState>((set, get) => ({
  cacheMap: {},
  get: (key) => get().cacheMap[key],
  set: (key, data) =>
    set((state) => ({
      cacheMap: {
        ...state.cacheMap,
        [key]: data,
      },
    })),
}))

// pages/list.tsx
import { WindowVirtualizedList } from 'virtua-restoration'
import { useVirtualListStore } from './store/virtualListStore'

const cacheProvider = {
  get: () => useVirtualListStore.getState().get('feed'),
  set: (data) => useVirtualListStore.getState().set('feed', data),
}

<WindowVirtualizedList cacheKey="feed" cacheSource="custom" customProvider={cacheProvider}>
  {/* children */}
</WindowVirtualizedList>

⚙️ Props

Prop	Type	Description
cacheKey	string	Unique outline where scroll/cache data will be stored
children	React.ReactNode	List content (items to be rendered virtually)
cacheSource	sessionStorage localStorage custom	Where to store the cache (default: sessionStorage)
customProvider	CacheProvider	Get/set functions to use if cacheSource is custom

🛠 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see the LICENSE file for details.