Retool List View & Grid View Repeatables: Complete Guide

Retool's new List View and Grid View Repeatables are a ground-up rebuild of one of the platform's most-used components. If you've been relying on the legacy Repeatable component to display dynamic lists of data, this guide covers everything you need to know — how to attach a datasource, use the item variable, understand performance trade-offs, and navigate the current limitations that are tripping up teams mid-build.

What Changed: Legacy Repeatables vs. New List View and Grid View

The old Repeatable component worked, but it had real constraints — no virtualization, limited scoping, and patchy performance at scale. Retool replaced it with two dedicated components: List View and Grid View. Both share the same core architecture but are optimized for different layout patterns. If your existing apps use the legacy Repeatable, expect to do some rebuilding — but the payoff is a faster, more flexible component model.

How to Attach a Datasource to a Retool List View

Every List View or Grid View needs a datasource to know how many instances to render and what data to pass into each one. Here's how to set it up:

• Open the List View or Grid View component in your Retool app.
• In the component's settings panel, find the Data field.
• Select an existing query (e.g. getUsers), a variable, or write a JavaScript expression directly.
• The component will render one instance per row in your datasource automatically.

This replaces the old approach of manually binding repeated components and gives you a single source of truth for both the count and the content of your list items.

Using the item Variable Inside a Repeatable

Once your datasource is connected, every child component inside the List View or Grid View has access to a special keyword: item. This refers to the current row's data from your datasource — think of it as the loop variable in a forEach.

For example, if your query returns a list of users, you can bind a Text component's value to {{item.name}} or {{item.email}} and each instance will render the correct data for that row.

If you're working with nested Repeatables, you can avoid scope collisions by referencing the parent explicitly:

• {{listView1.item.fieldName}} — accesses the outer list's current item
• {{listView2.item.fieldName}} — accesses the inner list's current item

The legacy variables i (index) and ri (row index) are still available if you need them for positional logic.

Virtualization and Performance: What It Means for Your App

The new List View is virtualized, which means Retool only renders the items currently visible in the viewport rather than all items at once. This is a significant improvement for lists with hundreds of rows.

However, virtualization comes with a trade-off you need to know about: you cannot index into components inside a Repeatable to read their state. For example, trying to access listView1.item[2].textInput1.value won't work. Retool doesn't keep all component instances alive in memory simultaneously, so their properties aren't accessible from outside the Repeatable scope.

The recommended workaround is to use event handlers inside the Repeatable to write state changes back to a variable or query as they happen, rather than trying to read component state from outside after the fact.

Known Limitation: Resetting Component Values Across All Rows

One of the most commonly reported pain points with the new List View is the inability to programmatically reset all instances of a component — for example, clearing every textInput across all rows at once. Because of the scope limitations tied to virtualization, there is currently no direct method to do this.

The best available workaround is to store your input state in a variable or localStorage object keyed by row identifier, and reset that data object. When the datasource updates, the child components will re-render with the cleared values. It's more architecture work upfront, but it keeps your state management outside the Repeatable where you can control it.

Grid View Performance with Large Datasets

If you're using Grid View with 100+ items that include images and checkboxes, you may hit rendering stutters — especially on scroll or edit. This is a known issue. A practical short-term fix is to use Retool's native Image Grid component for display-only use cases, which handles large image sets more smoothly. The downside is you lose interactive elements like checkboxes and custom event handlers. For interactive grids at scale, keep your item template as lean as possible — remove components you don't need and defer loading heavy assets where you can.

What's Coming: Events and Aggregation Features

The legacy list view didn't support events like onChange, and the new version doesn't either — yet. Retool has confirmed that event support and aggregation features are on the roadmap. Aggregation will let you compute values across all instances of a Repeatable (think totals, counts, or collected form values), which will address many of the current workarounds teams are building manually.

If you have specific aggregation use cases, Retool's team is actively collecting feedback before building it out — it's worth adding your input while the feature is still being scoped.

Quick Reference: New Retool List View Cheat Sheet

• Attach data via query, variable, or JS expression in the Data field
• Use item to access the current row's data inside the Repeatable
• Use listView1.item or listView2.item for nested scope disambiguation
• Use i or ri for index-based logic
• Do not try to index into child component properties from outside the Repeatable
• Use event handlers inside the Repeatable to push state changes to external variables
• Keep Grid View item templates lean for better scroll performance at scale

The new List View and Grid View components are a meaningful upgrade to Retool's Repeatables. The virtualization gains are real, the item variable makes binding cleaner, and the datasource model is more explicit. The indexing limitation is a genuine gap right now, but it's solvable with deliberate state management — and it should close once aggregation ships.