Generic Loop Scroll Rect

A high-performance, virtualized scroll view system for Unity. This package renders only visible items and reuses UI elements through object pooling, enabling smooth scrolling through thousands of items without performance degradation or garbage collection spikes.

---

🚀 Features

• Virtualized rendering – only visible items are rendered and updated
• Object pooling – automatic item recycling with zero allocation during scrolling
• High performance – handles 10,000+ items smoothly on mobile and low-end devices
• Zero-GC runtime – no allocations during scroll updates
• Generic type-safe binding – strongly typed data → UI mapping with ScrollRectItem<T>
• Vertical and horizontal scroll directions fully supported
• Multiple layouts – works with VerticalLayoutGroup, HorizontalLayoutGroup, and GridLayoutGroup
• Smooth scrolling – built-in inertia, elasticity, and clamped movement
• Easy integration – extends Unity's UI system with familiar components

---

📦 Installation

Unity Package Manager (Git URL)

1. Open Window → Package Manager
2. Click the + button → Add package from git URL
3. Enter the repository URL:

https://github.com/AtaYanki/GenericLoopScrollRect.git

4. Wait for Unity to download and import the package

Requirements:

• Unity 6000.0 or newer
• TextMeshPro (for samples)

---

🛠️ How It Works

The virtualization system optimizes scrolling through:

1. Viewport detection – calculates which items are currently visible
2. Pool management – retrieves inactive items from the object pool
3. Data binding – updates pooled items with correct data at runtime
4. Recycling – returns off-screen items to the pool for reuse

This architecture minimizes memory footprint and eliminates GC allocations during scrolling.

---

📘 Quick Start

1. Create Your Data Model

Define a simple data class to represent your list items:

public class PlayerData
{
    public string Name;
    public int Level;
    
    public PlayerData(string name, int level)
    {
        Name = name;
        Level = level;
    }
}

2. Create Your Item View

Create a UI item prefab and attach a script inheriting from ScrollRectItem<T>:

using UnityEngine;
using TMPro;
using AtaYanki.GenericScrollRect;

public class PlayerItem : ScrollRectItem<PlayerData>
{
    [SerializeField] private TextMeshProUGUI nameText;
    [SerializeField] private TextMeshProUGUI levelText;

    public override void UpdateData(PlayerData data)
    {
        if (data != null)
        {
            nameText.text = data.Name;
            levelText.text = "Level " + data.Level;
        }
    }
}

Note: The prefab must have a LayoutElement component (auto-added via RequireComponent).

3. Create Your Scroll Controller

Create a MonoBehaviour that inherits from ScrollRect<T>:

using System.Collections.Generic;
using UnityEngine;
using AtaYanki.GenericScrollRect;

public class PlayerListController : ScrollRect<PlayerData>
{
    private List<PlayerData> _playerList = new List<PlayerData>();
    
    public override List<PlayerData> ItemDataList => _playerList;

    void Awake()
    {
        // Populate your data
        for (int i = 0; i < 1000; i++)
        {
            _playerList.Add(new PlayerData($"Player {i}", i));
        }
    }

    protected override void OnItemClick(int index)
    {
        Debug.Log($"Clicked: {ItemDataList[index].Name}");
    }
}

4. Set Up the Scene

1. Create a Scroll View via GameObject → UI → Scroll View
2. Delete the default ScrollRect component
3. Add one of these components instead:
   • LoopVerticalScrollRect (for vertical scrolling)
   • LoopHorizontalScrollRect (for horizontal scrolling)
4. Add your controller script (e.g., PlayerListController)
5. Configure the controller:
   • Assign the Loop Scroll Rect component
   • Assign your Item Prefab (the one with PlayerItem script)
6. Add a VerticalLayoutGroup (or HorizontalLayoutGroup) to the Content object
7. Configure padding and spacing as needed

5. Run and Test

Press Play. The scroll view will automatically populate with your data and recycle items as you scroll.

---

🎯 Advanced Usage

Updating the List at Runtime

// Modify your data
ItemDataList.Add(new PlayerData("New Player", 999));

// Refresh the view
UpdateView();

Scrolling to a Specific Item

// Scroll to index 50 with speed 1000
ScrollToCell(50, 1000);

Handling Item Creation

Override OnItemCreated to configure items when first instantiated:

protected override void OnItemCreated(ScrollRectItem<PlayerData> item)
{
    // Configure item on first creation
    item.transform.localScale = Vector3.one;
}

---

📂 Package Structure

Runtime/
  ├── LoopScrollRectBase.cs          # Core virtualization logic
  ├── LoopScrollRect.cs              # Abstract scroll implementation
  ├── LoopVerticalScrollRect.cs      # Vertical scroll component
  ├── LoopHorizontalScrollRect.cs    # Horizontal scroll component
  ├── ScrollRect.cs                  # Generic scroll wrapper
  ├── ScrollRectItem.cs              # Abstract item base class
  ├── LoopScrollDataSource.cs        # Data provider interface
  ├── LoopScrollPrefabSource.cs      # Pool management interface
  └── LoopScrollSizeHelper.cs        # Dynamic sizing helper

Editor/
  ├── LoopScrollRectInspector.cs     # Custom inspector
  └── SGMenuOptions.cs               # Editor menu integration

Samples/
  ├── Scenes/SampleScene.unity       # Example scene
  ├── Scripts/
  │   ├── SampleData.cs              # Example data model
  │   ├── SampleLoopScrollRectItem.cs # Example item view
  │   └── SampleLoopScrollRect.cs    # Example controller
  └── UI/SampleScrollRectItem.prefab # Example prefab

---

⚙️ API Reference

ScrollRect<T> (Abstract Base Class)

Properties:

• abstract List<T> ItemDataList { get; } – Override to provide your data source

Methods:

• void UpdateView() – Refresh the scroll view (call after modifying data)
• void UpdateViewDelayed() – Refresh with 0.2s delay (useful for animations)
• void ScrollToCell(int index, int speed) – Scroll to specific item with speed
• protected abstract void OnItemClick(int index) – Handle item click events
• protected virtual void OnItemCreated(ScrollRectItem<T> item) – Configure new items

ScrollRectItem<T> (Abstract Base Class)

Properties:

• int ItemIndex – Current item index (read-only)
• Action<int> onClickAction – Click callback (automatically set)

Methods:

• abstract void UpdateData(T data) – Override to bind data to UI elements
• void UpdateIndex(int index) – Updates the item's index (called internally)
• virtual void RefreshUI(int index) – Override for custom UI refresh logic
• protected void OnItemClick() – Call this from UI button events

---

🎨 Best Practices

Performance Optimization

1. Keep UpdateData() fast – avoid complex calculations or asset loading
2. Use object pooling for nested elements – pool complex child objects
3. Limit layout rebuilds – minimize LayoutElement changes during runtime
4. Cache references – store component references in Awake() or Start()

Layout Configuration

1. VerticalLayoutGroup settings:

   • Set Child Force Expand → Width: ✓, Height: ✗
   • Configure Padding and Spacing as needed
   • Enable Child Control Size → Height: ✓

2. HorizontalLayoutGroup settings:

   • Set Child Force Expand → Width: ✗, Height: ✓
   • Configure Padding and Spacing as needed
   • Enable Child Control Size → Width: ✓

3. GridLayoutGroup settings:

   • Set Cell Size to match your item dimensions
   • Configure Constraint (Fixed Column/Row Count)
   • Set appropriate Spacing

Data Management

// ✅ Good: Modify data, then update view
ItemDataList.Add(newItem);
UpdateView();

// ✅ Good: Batch modifications
ItemDataList.AddRange(newItems);
UpdateView();

// ❌ Bad: Updating view multiple times
ItemDataList.Add(newItem1);
UpdateView(); // Expensive!
ItemDataList.Add(newItem2);
UpdateView(); // Expensive!

---

🧪 Included Sample

The package includes a functional sample demonstrating:

• Basic vertical scrolling setup
• Data model implementation (SampleData)
• Item view implementation (SampleLoopScrollRectItem)
• Controller implementation (SampleLoopScrollRect)
• Click handling and data binding

To import:

1. Open Package Manager
2. Find Generic Loop Scroll Rect
3. Expand Samples
4. Click Import next to the sample

---

📝 Changelog

See CHANGELOG.md for version history.

v1.0.0 (18-11-2025)

• ✨ Initial public release
• 🎯 Core virtualization engine with object pooling
• 🔧 Generic type-safe item binding system
• ↕️ Vertical & horizontal scroll support
• 🎨 GridLayoutGroup compatibility
• 📱 Zero-GC runtime performance
• 📚 Complete sample scene and documentation

---

🔧 Troubleshooting

Issue: Items not appearing

• Ensure LoopVerticalScrollRect or LoopHorizontalScrollRect is assigned
• Check that ItemDataList is populated before Start() is called
• Verify item prefab has a LayoutElement component

Issue: Items displaying incorrect data

• Make sure UpdateData() properly assigns all UI elements
• Check that your data list index matches expectations

Issue: Scrolling feels choppy

• Optimize your UpdateData() method (avoid allocations)
• Reduce complexity of item prefabs
• Check that LayoutElement sizes are set correctly

Issue: Items not recycling

• Verify ReturnObject() is being called (handled automatically)
• Check console for pool-related errors

---

📄 License

MIT License - See LICENSE for details.

---

🙌 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with clear commit messages
4. Submit a pull request

Areas for contribution:

• Additional sample scenes
• Performance improvements
• Bug fixes
• Documentation improvements

---

💬 Support

Found a bug or have a feature request?

• Open an issue on GitHub
• Provide Unity version, error logs, and reproduction steps

Need help integrating?

• Check the included sample scene
• Review the Quick Start guide above
• Open a discussion on GitHub

---

🏷️ Keywords

Unity, UI, ScrollView, ScrollRect, Virtualization, Object Pooling, Performance, Mobile, UGUI, List, RecyclerView, ListView