@arcmantle/infinite-scroller

A high-performance infinite scrolling component that virtualizes large lists by only rendering visible items. Built with Lit and optimized for smooth scrolling with thousands of items.

Features

• 🚀 Virtual Scrolling: Only renders items that are visible in the viewport
• ⚡ High Performance: Handles thousands of items with minimal memory usage
• 🔄 Dynamic Buffering: Automatically calculates optimal buffer sizes based on viewport
• 📱 Responsive: Adapts to container size changes automatically
• 🎯 Smooth Scrolling: Uses CSS transforms and optimized rendering for 60fps performance
• 🛠️ Abstract Base Class: Extend and customize for your specific use cases
• 🎨 Styleable: Full CSS customization with CSS custom properties

Installation

npm install @arcmantle/infinite-scroller

pnpm add @arcmantle/infinite-scroller

yarn add @arcmantle/infinite-scroller

Basic Usage

The InfiniteScroller is an abstract base class that you extend to create your own infinite scrolling components:

import { InfiniteScroller } from '@arcmantle/infinite-scroller';
import { customElement } from 'lit/decorators.js';

@customElement('my-list')
export class MyListComponent extends InfiniteScroller {

  constructor() {
    super();
    this.maxIndex = 10000; // Total number of items
  }

  // Create the DOM element for each list item
  protected createElement(): HTMLElement {
    return document.createElement('my-list-item');
  }

  // Update the element content based on its index
  protected updateElement(element: HTMLElement, index: number): void {
    if (index < 0 || index >= this.maxIndex) {
      element.style.visibility = 'hidden';
      return;
    }

    element.style.visibility = 'visible';
    element.textContent = `Item ${index}`;
  }
}

Advanced Example

Here's a more complete example with custom styling and data:

import { css, html, LitElement } from 'lit';
import { customElement, property } from 'lit/decorators.js';
import { InfiniteScroller } from '@arcmantle/infinite-scroller';

interface ListItem {
  id: string;
  title: string;
  description: string;
}

@customElement('data-list')
export class DataListComponent extends InfiniteScroller {

  @property({ type: Array })
  data: ListItem[] = [];

  constructor() {
    super();
    this.maxIndex = this.data.length;
  }

  protected createElement(): HTMLElement {
    return document.createElement('data-list-item');
  }

  protected updateElement(element: DataListItemComponent, index: number): void {
    if (index < 0 || index >= this.data.length) {
      element.style.visibility = 'hidden';
      return;
    }

    element.style.visibility = 'visible';
    element.item = this.data[index];
  }

  // Handle infinite loading
  protected override onScroll(): void {
    super.onScroll();

    // Load more data when near the end
    if ((this.maxIndex - this.position) < 30) {
      this.loadMoreData();
    }
  }

  private async loadMoreData(): Promise<void> {
    const newData = await fetchMoreItems();
    this.data = [...this.data, ...newData];
    this.maxIndex = this.data.length;
  }

  static override styles = css`
    :host {
      --item-height: 80px;
      height: 400px;
      border: 1px solid #ccc;
    }
  `;
}

@customElement('data-list-item')
export class DataListItemComponent extends LitElement {

  @property({ type: Object })
  item?: ListItem;

  protected render() {
    if (!this.item) return html``;

    return html`
      <div class="item">
        <h3>${this.item.title}</h3>
        <p>${this.item.description}</p>
      </div>
    `;
  }

  static styles = css`
    :host {
      display: block;
      padding: 16px;
      border-bottom: 1px solid #eee;
    }

    .item h3 {
      margin: 0 0 8px 0;
      font-size: 16px;
    }

    .item p {
      margin: 0;
      color: #666;
      font-size: 14px;
    }
  `;
}

Properties

Core Properties

| Property | Type | Description | |----------|------|-------------| | maxIndex | number | Total number of items in the list | | itemHeight | number | Height of each item in pixels | | bufferSize | number | Number of items to render outside viewport (calculated automatically) | | position | number | Current scroll position as item index (can be fractional) |

CSS Custom Properties

| Property | Default | Description | |----------|---------|-------------| | --item-height | 60px | Height of each list item |

Methods

Abstract Methods (Must Implement)

// Create a new DOM element for list items
protected abstract createElement(): HTMLElement;

// Update element content based on its index position
protected abstract updateElement(element: HTMLElement, index: number): void;

Public Methods

// Get/set scroll position by item index
scroller.position = 100; // Scroll to item 100
const currentPosition = scroller.position;

Lifecycle Hooks

// Override to handle scroll events
protected onScroll(): void {
  super.onScroll();
  // Your custom scroll logic
}

// Override to handle resize events
protected onResize(entries?: ResizeObserverEntry[]): boolean {
  const result = super.onResize(entries);
  // Your custom resize logic
  return result;
}

Architecture

Virtual Scrolling Strategy

The infinite scroller uses a dual-buffer strategy:

1. Two Buffers: Maintains two buffer zones that contain rendered items
2. Dynamic Translation: Buffers are translated vertically as the user scrolls
3. Automatic Sizing: Buffer size is calculated based on viewport height
4. Smart Updates: Only updates items that are actually visible

Buffer Management

┌─────────────────┐
│   Buffer 0      │ ← Contains items 0-19
├─────────────────┤
│   Buffer 1      │ ← Contains items 20-39
├─────────────────┤
│   (Virtual)     │ ← Items 40+ not rendered
└─────────────────┘

As the user scrolls down:

• Buffer 0 moves below Buffer 1 and updates to show items 40-59
• Buffer 1 continues showing items 20-39
• The cycle continues seamlessly

Performance Optimizations

• CSS Transforms: Uses translate3d() for hardware acceleration
• Passive Scrolling: Scroll listeners are passive for better performance
• ResizeObserver: Efficiently handles container size changes
• Minimal DOM: Only creates elements that fit in the buffers
• Smart Updates: Only updates visible elements during scroll

Events

Custom Events

// Fired when the scroller is ready and initialized
scroller.addEventListener('ready', (event) => {
  console.log('Scroller is ready');
});

Native Events

The component supports all standard scroll events on the internal scroller element.

Styling

Basic Styling

my-list {
  --item-height: 100px;
  height: 500px;
  width: 100%;
  border: 1px solid #ddd;
}

Advanced Styling with CSS Parts

my-list::part(scroller) {
  border-radius: 8px;
  background: #f9f9f9;
}

my-list::part(buffer) {
  /* Style the buffer containers */
}

Responsive Design

my-list {
  --item-height: 60px;
  height: 100%;
}

@media (max-width: 768px) {
  my-list {
    --item-height: 80px;
  }
}

Common Patterns

Infinite Loading

protected override onScroll(): void {
  super.onScroll();

  const threshold = 50; // Items from end
  if ((this.maxIndex - this.position) < threshold) {
    this.loadMoreItems();
  }
}

private async loadMoreItems(): Promise<void> {
  if (this.loading) return;

  this.loading = true;
  const newItems = await this.dataService.fetchMore();
  this.data.push(...newItems);
  this.maxIndex = this.data.length;
  this.loading = false;
}

Search and Filter

private filteredData: Item[] = [];

search(query: string): void {
  this.filteredData = this.allData.filter(item =>
    item.title.toLowerCase().includes(query.toLowerCase())
  );
  this.maxIndex = this.filteredData.length;
  this.position = 0; // Reset to top
}

protected updateElement(element: HTMLElement, index: number): void {
  const item = this.filteredData[index];
  // Update element with filtered data
}

Dynamic Item Heights

For variable item heights, calculate and cache heights:

private itemHeights = new Map<number, number>();

protected override get itemHeight(): number {
  // Return average height or base height
  return this.averageItemHeight || 60;
}

protected updateElement(element: HTMLElement, index: number): void {
  super.updateElement(element, index);

  // Measure and cache actual height
  requestAnimationFrame(() => {
    const height = element.getBoundingClientRect().height;
    this.itemHeights.set(index, height);
  });
}

Browser Support

• Modern Browsers: Chrome 69+, Firefox 63+, Safari 12+
• Required Features:
  • ResizeObserver API
  • CSS Grid Layout
  • CSS Custom Properties
  • ES2020+ JavaScript features

Performance Tips

1. Keep Updates Light: Minimize work in updateElement()
2. Use CSS for Styling: Prefer CSS over JavaScript for visual changes
3. Batch DOM Updates: Group multiple changes together
4. Profile Your Code: Use browser dev tools to identify bottlenecks
5. Consider Item Complexity: Simpler items = better performance

Troubleshooting

Common Issues

Items not updating correctly:

• Ensure updateElement() handles all edge cases
• Check that maxIndex is set correctly

Scrolling feels sluggish:

• Reduce complexity in updateElement()
• Check for memory leaks in item components

Layout jumping:

• Ensure consistent --item-height values
• Avoid dynamic height changes during scroll

Buffer size warnings:

• Increase container height or decrease item height
• Check for CSS issues affecting measurements

Development

Building

pnpm install
pnpm build

Development Server

pnpm dev

Testing

pnpm test

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

This project is licensed under the Apache 2.0 License - see the Apache License 2.0 for details.

Related Packages

This component is part of the @arcmantle ecosystem:

• @arcmantle/library - Core utilities and helper functions
• lit - The underlying web component framework

.