Webf Infinite Scrolling

• ✅ Automatically virtualizes (recycles) views
• ✅ Maintains 60fps scrolling with thousands of items
• ✅ Provides native pull-to-refresh and load-more
• ✅ Zero configuration - optimization happens automatically

Critical Structure Requirement

⚠️ IMPORTANT: For Flutter optimization to work, each list item must be a direct child of WebFListView:

✅ CORRECT: Direct Children

<WebFListView>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
  {/* Each item is a direct child */}
</WebFListView>

❌ WRONG: Wrapped in Container

<WebFListView>
  <div>
    {/* DON'T wrap items in a container div */}
    <div>Item 1</div>
    <div>Item 2</div>
    <div>Item 3</div>
  </div>
</WebFListView>

Why this matters: Flutter's ListView requires direct children to perform view recycling. If items are wrapped in a container, Flutter sees only one child (the container) and cannot optimize individual items.

React Setup

Installation

npm install @openwebf/react-core-ui

Basic Scrolling List

import { WebFListView } from '@openwebf/react-core-ui';

function ProductList() {
  const products = [
    { id: 1, name: 'Product 1', price: 19.99 },
    { id: 2, name: 'Product 2', price: 29.99 },
    { id: 3, name: 'Product 3', price: 39.99 },
    // ... hundreds or thousands of items
  ];

  return (
    <WebFListView scrollDirection="vertical" shrinkWrap={true}>
      {products.map(product => (
        // ✅ Each item is a direct child
        <div key={product.id} className="product-card">
          <h3>{product.name}</h3>
          <p>${product.price}</p>
        </div>
      ))}
    </WebFListView>
  );
}

Infinite Scrolling with Load More

import { WebFListView, WebFListViewElement } from '@openwebf/react-core-ui';
import { useRef, useState } from 'react';

function InfiniteList() {
  const listRef = useRef<WebFListViewElement>(null);
  const [items, setItems] = useState([1, 2, 3, 4, 5]);
  const [page, setPage] = useState(1);

  const handleLoadMore = async () => {
    try {
      // Simulate API call
      await new Promise(resolve => setTimeout(resolve, 1000));

      // Fetch next page
      const newItems = Array.from(
        { length: 5 },
        (_, i) => items.length + i + 1
      );

      setItems(prev => [...prev, ...newItems]);
      setPage(prev => prev + 1);

      // Check if there's more data
      const hasMore = page < 10; // Example: 10 pages max

      // Notify WebFListView that loading finished
      listRef.current?.finishLoad(hasMore ? 'success' : 'noMore');
    } catch (error) {
      // Notify failure
      listRef.current?.finishLoad('fail');
    }
  };

  return (
    <WebFListView
      ref={listRef}
      onLoadMore={handleLoadMore}
      scrollDirection="vertical"
      shrinkWrap={true}
    >
      {items.map(item => (
        <div key={item} className="item">
          Item {item}
        </div>
      ))}
    </WebFListView>
  );
}

Pull-to-Refresh

import { WebFListView, WebFListViewElement } from '@openwebf/react-core-ui';
import { useRef, useState } from 'react';

function RefreshableList() {
  const listRef = useRef<WebFListViewElement>(null);
  const [items, setItems] = useState([1, 2, 3, 4, 5]);

  const handleRefresh = async () => {
    try {
      // Simulate API call
      await new Promise(resolve => setTimeout(resolve, 1000));

      // Fetch fresh data
      const freshItems = [1, 2, 3, 4, 5];
      setItems(freshItems);

      // Notify WebFListView that refresh finished
      listRef.current?.finishRefresh('success');
    } catch (error) {
      // Notify failure
      listRef.current?.finishRefresh('fail');
    }
  };

  return (
    <WebFListView
      ref={listRef}
      onRefresh={handleRefresh}
      scrollDirection="vertical"
      shrinkWrap={true}
    >
      {items.map(item => (
        <div key={item} className="item">
          Item {item}
        </div>
      ))}
    </WebFListView>
  );
}

Combined: Pull-to-Refresh + Infinite Scrolling

import { WebFListView, WebFListViewElement } from '@openwebf/react-core-ui';
import { useRef, useState } from 'react';

function FeedList() {
  const listRef = useRef<WebFListViewElement>(null);
  const [posts, setPosts] = useState([
    { id: 1, title: 'Post 1', content: 'Content 1' },
    { id: 2, title: 'Post 2', content: 'Content 2' },
    { id: 3, title: 'Post 3', content: 'Content 3' },
  ]);
  const [page, setPage] = useState(1);

  const handleRefresh = async () => {
    try {
      // Fetch latest posts
      const response = await fetch('/api/posts?page=1');
      const freshPosts = await response.json();

      setPosts(freshPosts);
      setPage(1);

      listRef.current?.finishRefresh('success');
    } catch (error) {
      listRef.current?.finishRefresh('fail');
    }
  };

  const handleLoadMore = async () => {
    try {
      const nextPage = page + 1;

      // Fetch next page
      const response = await fetch(`/api/posts?page=${nextPage}`);
      const newPosts = await response.json();

      setPosts(prev => [...prev, ...newPosts]);
      setPage(nextPage);

      // Check if more data exists
      const hasMore = newPosts.length > 0;
      listRef.current?.finishLoad(hasMore ? 'success' : 'noMore');
    } catch (error) {
      listRef.current?.finishLoad('fail');
    }
  };

  return (
    <WebFListView
      ref={listRef}
      onRefresh={handleRefresh}
      onLoadMore={handleLoadMore}
      scrollDirection="vertical"
      shrinkWrap={true}
      style={{ height: '100vh' }}
    >
      {posts.map(post => (
        <article key={post.id} className="post-card">
          <h2>{post.title}</h2>
          <p>{post.content}</p>
        </article>
      ))}
    </WebFListView>
  );
}

Vue Setup

Installation

npm install @openwebf/vue-core-ui

Setup Global Types

In your src/env.d.ts or src/main.ts:

import '@openwebf/vue-core-ui';

Basic Scrolling List

<template>
  <webf-list-view scroll-direction="vertical" :shrink-wrap="true">
    <div v-for="product in products" :key="product.id" class="product-card">
      <h3>{{ product.name }}</h3>
      <p>${{ product.price }}</p>
    </div>
  </webf-list-view>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const products = ref([
  { id: 1, name: 'Product 1', price: 19.99 },
  { id: 2, name: 'Product 2', price: 29.99 },
  { id: 3, name: 'Product 3', price: 39.99 },
]);
</script>

Infinite Scrolling with Load More

<template>
  <webf-list-view
    ref="listRef"
    @loadmore="handleLoadMore"
    scroll-direction="vertical"
    :shrink-wrap="true"
  >
    <div v-for="item in items" :key="item" class="item">
      Item {{ item }}
    </div>
  </webf-list-view>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const listRef = ref<HTMLElement>();
const items = ref([1, 2, 3, 4, 5]);
const page = ref(1);

async function handleLoadMore() {
  try {
    // Simulate API call
    await new Promise(resolve => setTimeout(resolve, 1000));

    // Fetch next page
    const newItems = Array.from(
      { length: 5 },
      (_, i) => items.value.length + i + 1
    );

    items.value.push(...newItems);
    page.value++;

    // Check if there's more data
    const hasMore = page.value < 10;

    // Notify WebFListView
    (listRef.value as any)?.finishLoad(hasMore ? 'success' : 'noMore');
  } catch (error) {
    (listRef.value as any)?.finishLoad('fail');
  }
}
</script>

Pull-to-Refresh

<template>
  <webf-list-view
    ref="listRef"
    @refresh="handleRefresh"
    scroll-direction="vertical"
    :shrink-wrap="true"
  >
    <div v-for="item in items" :key="item" class="item">
      Item {{ item }}
    </div>
  </webf-list-view>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const listRef = ref<HTMLElement>();
const items = ref([1, 2, 3, 4, 5]);

async function handleRefresh() {
  try {
    // Simulate API call
    await new Promise(resolve => setTimeout(resolve, 1000));

    // Fetch fresh data
    items.value = [1, 2, 3, 4, 5];

    // Notify WebFListView
    (listRef.value as any)?.finishRefresh('success');
  } catch (error) {
    (listRef.value as any)?.finishRefresh('fail');
  }
}
</script>

Props and Configuration

WebFListView Props

Ref Methods (React) / Element Methods (Vue)

Result Values

• 'success' - Operation succeeded, more data available
• 'fail' - Operation failed (shows error state)
• 'noMore' - No more data to load (hides footer/shows "no more" message)

Common Patterns

Pattern 1: Search with Results List

import { WebFListView, WebFListViewElement } from '@openwebf/react-core-ui';
import { useRef, useState } from 'react';

function SearchResults() {
  const listRef = useRef<WebFListViewElement>(null);
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);

  const handleSearch = async (searchQuery: string) => {
    setQuery(searchQuery);

    // Fetch search results
    const response = await fetch(`/api/search?q=${searchQuery}`);
    const data = await response.json();

    setResults(data.results);
  };

  const handleLoadMore = async () => {
    try {
      const response = await fetch(
        `/api/search?q=${query}&offset=${results.length}`
      );
      const data = await response.json();

      setResults(prev => [...prev, ...data.results]);

      listRef.current?.finishLoad(
        data.results.length > 0 ? 'success' : 'noMore'
      );
    } catch (error) {
      listRef.current?.finishLoad('fail');
    }
  };

  return (
    <div>
      <input
        type="text"
        placeholder="Search..."
        onChange={(e) => handleSearch(e.target.value)}
      />

      <WebFListView
        ref={listRef}
        onLoadMore={handleLoadMore}
        scrollDirection="vertical"
        shrinkWrap={true}
      >
        {results.map(result => (
          <div key={result.id} className="search-result">
            {result.title}
          </div>
        ))}
      </WebFListView>
    </div>
  );
}

Pattern 2: Chat Messages (Reverse List)

For chat-style UIs where new messages appear at the bottom:

import { WebFListView, WebFListViewElement } from '@openwebf/react-core-ui';
import { useRef, useState, useEffect } from 'react';

function ChatMessages() {
  const listRef = useRef<WebFListViewElement>(null);
  const [messages, setMessages] = useState([
    { id: 1, text: 'Hello', timestamp: Date.now() },
    { id: 2, text: 'Hi there!', timestamp: Date.now() },
  ]);

  // Load older messages when scrolling to top
  const handleLoadMore = async () => {
    try {
      // In real app, fetch older messages before first message
      const oldestId = messages[0]?.id;
      const response = await fetch(`/api/messages?before=${oldestId}`);
      const olderMessages = await response.json();

      // Prepend older messages
      setMessages(prev => [...olderMessages, ...prev]);

      listRef.current?.finishLoad(
        olderMessages.length > 0 ? 'success' : 'noMore'
      );
    } catch (error) {
      listRef.current?.finishLoad('fail');
    }
  };

  return (
    <WebFListView
      ref={listRef}
      onLoadMore={handleLoadMore}
      scrollDirection="vertical"
      shrinkWrap={true}
      style={{
        height: '100vh',
        display: 'flex',
        flexDirection: 'column-reverse' // Reverse order
      }}
    >
      {messages.map(message => (
        <div key={message.id} className="message">
          {message.text}
        </div>
      ))}
    </WebFListView>
  );
}

Pattern 3: Horizontal Scrolling Gallery

import { WebFListView } from '@openwebf/react-core-ui';

function ImageGallery({ images }) {
  return (
    <WebFListView
      scrollDirection="horizontal"
      shrinkWrap={true}
      style={{
        display: 'flex',
        height: '200px',
        gap: '10px'
      }}
    >
      {images.map(image => (
        <img
          key={image.id}
          src={image.url}
          alt={image.title}
          style={{
            width: '150px',
            height: '150px',
            objectFit: 'cover',
            flexShrink: 0  // Prevent shrinking
          }}
        />
      ))}
    </WebFListView>
  );
}

Common Mistakes

Mistake 1: Wrapping Items in Container

// ❌ WRONG - Items wrapped in container div
<WebFListView>
  <div className="items-container">
    {items.map(item => <div key={item}>{item}</div>)}
  </div>
</WebFListView>

// ✅ CORRECT - Items are direct children
<WebFListView>
  {items.map(item => <div key={item}>{item}</div>)}
</WebFListView>

Why: Flutter's ListView needs direct children for view recycling to work.

Mistake 2: Forgetting to Call finishLoad/finishRefresh

// ❌ WRONG - Never calls finishLoad
const handleLoadMore = async () => {
  const data = await fetchData();
  setItems(prev => [...prev, ...data]);
  // finishLoad never called - loading indicator stuck!
};

// ✅ CORRECT - Always call finishLoad
const handleLoadMore = async () => {
  try {
    const data = await fetchData();
    setItems(prev => [...prev, ...data]);
    listRef.current?.finishLoad('success');
  } catch (error) {
    listRef.current?.finishLoad('fail');
  }
};

Mistake 3: Not Handling "No More Data" State

// ❌ WRONG - Always calls 'success', even when no data
const handleLoadMore = async () => {
  const data = await fetchData();
  setItems(prev => [...prev, ...data]);
  listRef.current?.finishLoad('success'); // Wrong if data is empty!
};

// ✅ CORRECT - Check if more data exists
const handleLoadMore = async () => {
  const data = await fetchData();
  setItems(prev => [...prev, ...data]);

  // Tell WebFListView there's no more data
  listRef.current?.finishLoad(data.length > 0 ? 'success' : 'noMore');
};

Mistake 4: Timeout Issues (Taking Too Long)

WebFListView has a 4-second timeout for refresh/load operations. If your operation takes longer, it will auto-fail.

// ❌ WRONG - Operation takes 10 seconds (will timeout)
const handleRefresh = async () => {
  await new Promise(resolve => setTimeout(resolve, 10000)); // 10s
  listRef.current?.finishRefresh('success'); // Too late!
};

// ✅ CORRECT - Complete within 4 seconds
const handleRefresh = async () => {
  try {
    // Use Promise.race to enforce timeout
    await Promise.race([
      fetchData(),
      new Promise((_, reject) =>
        setTimeout(() => reject(new Error('Timeout')), 3500)
      )
    ]);
    listRef.current?.finishRefresh('success');
  } catch (error) {
    listRef.current?.finishRefresh('fail');
  }
};

Performance Tips

1. Use Keys Correctly

Always provide unique, stable keys for list items:

// ✅ GOOD - Stable ID from data
{items.map(item => <div key={item.id}>{item.name}</div>)}

// ❌ BAD - Index as key (can cause bugs with dynamic lists)
{items.map((item, index) => <div key={index}>{item.name}</div>)}

2. Avoid Heavy Computations in Render

// ❌ BAD - Heavy computation on every render
<WebFListView>
  {items.map(item => (
    <div key={item.id}>
      {expensiveCalculation(item)} {/* Calculated on every render! */}
    </div>
  ))}
</WebFListView>

// ✅ GOOD - Memoize or pre-calculate
const processedItems = useMemo(
  () => items.map(item => ({ ...item, computed: expensiveCalculation(item) })),
  [items]
);

<WebFListView>
  {processedItems.map(item => (
    <div key={item.id}>{item.computed}</div>
  ))}
</WebFListView>

3. Optimize Item Components

// ✅ GOOD - Memoized item component
const ListItem = memo(({ item }) => (
  <div className="item">
    <h3>{item.title}</h3>
    <p>{item.description}</p>
  </div>
));

function MyList({ items }) {
  return (
    <WebFListView>
      {items.map(item => (
        <ListItem key={item.id} item={item} />
      ))}
    </WebFListView>
  );
}

4. Set Explicit Height for Scrolling

For full-screen lists, set explicit height:

<WebFListView
  style={{
    height: '100vh', // or specific pixel value
    overflow: 'auto'
  }}
>
  {/* items */}
</WebFListView>

Debugging

Check if finishLoad/finishRefresh is Called

Add logging to verify callbacks execute:

const handleLoadMore = async () => {
  console.log('🔄 Load more started');

  try {
    const data = await fetchData();
    setItems(prev => [...prev, ...data]);

    console.log('✅ Load more finished:', data.length, 'items');
    listRef.current?.finishLoad(data.length > 0 ? 'success' : 'noMore');
  } catch (error) {
    console.error('❌ Load more failed:', error);
    listRef.current?.finishLoad('fail');
  }
};

Verify Direct Children Structure

Use React DevTools or Vue DevTools to inspect the rendered structure. Ensure items are direct children of <webf-listview>:

<!-- ✅ CORRECT structure in DevTools -->
<webf-listview>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</webf-listview>

<!-- ❌ WRONG structure in DevTools -->
<webf-listview>
  <div class="wrapper">
    <div>Item 1</div>
    <div>Item 2</div>
  </div>
</webf-listview>

Resources

• React Core UI Package: /Users/andycall/workspace/webf/packages/react-core-ui/README.md
• Vue Core UI Package: /Users/andycall/workspace/webf/packages/vue-core-ui/README.md
• Complete Examples: See examples.md in this skill
• npm Packages:
  • https://www.npmjs.com/package/@openwebf/react-core-ui
  • https://www.npmjs.com/package/@openwebf/vue-core-ui

Key Takeaways

✅ DO:

• Use WebFListView for long scrolling lists
• Make each item a direct child (not wrapped in container)
• Always call finishLoad / finishRefresh after operations
• Use 'noMore' result when no more data exists
• Provide unique, stable keys for list items
• Set explicit height for full-screen lists

❌ DON'T:

• Wrap items in a container div
• Forget to call finish methods (loading indicator gets stuck)
• Use index as key for dynamic lists
• Let operations exceed 4-second timeout
• Use heavy computations in render without memoization
• Expect browser-style virtualization libraries (not needed!)

Quick Reference

# Install packages
npm install @openwebf/react-core-ui  # React
npm install @openwebf/vue-core-ui    # Vue

// React - Basic pattern
import { WebFListView, WebFListViewElement } from '@openwebf/react-core-ui';

const listRef = useRef<WebFListViewElement>(null);

<WebFListView
  ref={listRef}
  onRefresh={async () => {
    await refreshData();
    listRef.current?.finishRefresh('success');
  }}
  onLoadMore={async () => {
    const hasMore = await loadMore();
    listRef.current?.finishLoad(hasMore ? 'success' : 'noMore');
  }}
>
  {items.map(item => <div key={item.id}>{item.name}</div>)}
</WebFListView>

<!-- Vue - Basic pattern -->
<webf-list-view
  ref="listRef"
  @refresh="handleRefresh"
  @loadmore="handleLoadMore"
>
  <div v-for="item in items" :key="item.id">{{ item.name }}</div>
</webf-list-view>
```37:["$","$L3f",null,{"content":"$40","frontMatter":{"name":"webf-infinite-scrolling","description":"Create high-performance infinite scrolling lists with pull-to-refresh and load-more capabilities using WebFListView. Use when building feed-style UIs, product catalogs, chat messages, or any scrollable list that needs optimal performance with large datasets."}}]