React Dynamic Window 🪟

React virtualization library for efficiently rendering large scrollable lists with dynamic heights and expandable content.

🎮 Demo

Check out the live demo: https://rdw.surge.sh/

✨ Features

• 🚀 Virtualized Rendering: Only renders items that are visible in the viewport, optimizing performance for large lists
• 📏 Dynamic Heights: Supports items with varying heights using ResizeObserver for automatic height detection
• 🔄 Expandable Content: Built-in support for expandable/collapsible items with smooth animations
• 🔄 Infinite Loading: Seamless infinite scroll with support for loading both newer and older items
• 🎯 Buffer Management: Configurable buffer size for smooth scrolling experience
• 🎨 Customizable: Fully customizable item rendering and styling with flexible children props
• 📱 Responsive: Works on all screen sizes with adaptive viewport calculations
• 🔍 Smart Scroll Management: Intelligent scroll position restoration for dynamic content updates
• 🎮 External Controls: Supports external scroll controls with smooth animations

📦 Installation

1npm install react-dynamic-window
2# or
3yarn add react-dynamic-window
4# or
5pnpm add react-dynamic-window

🚀 Quick Start

1import { ReactDynamicWindow } from 'react-dynamic-window';
2
3function App() {
4  const items = Array.from({ length: 1000 }, (_, i) => ({
5    id: i,
6    title: `Item ${i}`,
7    content: `Content for item ${i}`,
8  }));
9
10  return (
11    <div style={{ width: '500px', height: '600px' }}>
12      <ReactDynamicWindow
13        className="list-item"
14        data={items}
15        itemHeight={150}
16        bufferSize={4}
17        onLoadMore={() => {
18          // Load more items
19        }}
20      >
21        {({ data, isExpanded, onClick }) => (
22          <div onClick={onClick}>
23            <h3>{data.title}</h3>
24            {isExpanded && <p>{data.content}</p>}
25          </div>
26        )}
27      </ReactDynamicWindow>
28    </div>
29  );
30}

🔧 Props

Prop	Type	Default	Description
data	T[]	Required	Array of items to render
itemHeight	number	150	Default height for each item (10-1000px)
bufferSize	number	4	Number of items to render outside viewport (1-20)
threshold	number	0.9	Scroll threshold for loading more items (0.1-1.0)
className	string	-	Custom CSS class for list items
hasLatestData	boolean	-	Indicates if latest data is available
controls	ReactDynamicWindowControls	-	External controls for scroll management
onLoadMore	() => void	Required	Callback when more items needed
onLoadLatest	() => Promise<boolean>	-	Callback to load latest items

🔄 Advanced Usage

Dynamic Heights with ResizeObserver

The library automatically handles dynamic heights using ResizeObserver, making it perfect for expandable content:

1<ReactDynamicWindow data={items}>
2  {({ data, isExpanded }) => (
3    <div>
4      <h3>{data.title}</h3>
5      {isExpanded && (
6        <div className="expandable-content">
7          <img src={data.image} alt={data.title} loading="lazy" />
8          <p>{data.description}</p>
9        </div>
10      )}
11    </div>
12  )}
13</ReactDynamicWindow>

External Controls

You can control the scroll behavior externally using the controls prop:

1const controls = {
2  scrollToTop: () => () => void,
3  // First function (provided by component) handles the scroll behavior
4  // Second function (user-defined) can be used for custom actions
5};
6
7<ReactDynamicWindow
8  controls={controls}
9  data={items}
10>
11  {/* ... */}
12</ReactDynamicWindow>
13
14// Later in your code
15const scrollFn = controls.scrollToTop({ behavior: 'smooth' });
16scrollFn(); // Execute the returned function

Infinite Loading

The component supports infinite scrolling in both directions: loading more items when scrolling down and loading latest items when scrolling to top.

1<ReactDynamicWindow
2  data={items}
3  hasLatestData={hasNewItems} // Flag indicating new items are available
4  onLoadMore={handleLoadMore} // Called when scrolling down
5  onLoadLatest={handleLoadLatest} // Called when scrolling to top
6>
7  {({ data }) => <ListItem data={data} />}
8</ReactDynamicWindow>

Key concepts:

• hasLatestData: Indicates whether new items are available at the top
• onLoadLatest: Triggered only when scrolling to top AND hasLatestData is true
• Return true from onLoadLatest if new items were loaded, false otherwise
• The component handles scroll position management automatically

Typical use cases:

• Real-time feeds where new content arrives periodically
• Chat or messaging interfaces
• Social media timelines

Custom Styling

The component accepts a className prop and provides full control over item styling:

1<ReactDynamicWindow className="custom-list-item" data={items}>
2  {({ data, isExpanded }) => (
3    <div className={`item ${isExpanded ? 'expanded' : ''}`}>
4      {/* Your custom item content */}
5    </div>
6  )}
7</ReactDynamicWindow>

🛠️ Technical Details

• Uses ResizeObserver for accurate dynamic height measurements
• Implements optimized scroll position restoration for dynamic content updates
• Supports both append and prepend modes with automatic scroll adjustment
• Provides type-safe props with runtime validation
• Implements memoization for optimal re-rendering
• Uses virtual DOM for efficient updates
• Handles window resize events automatically

🤝 Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

📝 MIT © [MNIII]