Skip to main content

Build list views to uniformly display your data

Learn how to display and interact with your data using list views.

note

This guide uses the updated List View component. The updated component is available on Cloud, as well as Self-hosted Retool on versions 3.28.3+. See the legacy version of this guide for using the legacy List View component.

List View components are a common way to display and interact with your data. You nest components within the list view and configure them to display certain values. You only have to do this once because the list view repeats the configuration for every entry in your data source. See the demo below for an example.

In the demo, the underlying configuration for displaying user names, emails, etc. is only done once. The configuration is then repeated for every user in the data source resulting in the grid-like view.

Add the component and specify the data​

Add a List View component to the canvas and select a Data source. You can write JavaScript, pass an array, or use query data as your data source. The only requirement is that the data source is an array (primitive and object arrays both work).

Set a primary key

Retool tries to set a primary key for List View components when you select a data source. If your app has multiple user input components, make sure the primary key is set correctly. This ensures your app state is correct after users make changes like adding or sorting data.

After selecting a data source, Retool seeds the component with containers for each item in your data source. You add components to the first container and they're automatically propagated to the other containers. Retool sets some default values, but you use the item and i variables to display data in each component.

The item variable​

The item variable corresponds to the value of an entry in your data source. It's equivalent to referencing listView1.data[i]. You can use item to access values in your data source, such as {{ item.id }} or {{ item.value }}.

The i variable​

The i variable is a number that represents the index of an entry in your data source. Since a list view is a repeatable component, each repeated instance has a different index which you can use to render and access unique values.

i is often used to iterate over a set of values and perform some kind of action. For example, you could iterate over an entire list view to update values, make API requests, send emails, etc. For example, this JavaScript transformer iterates over all the entries in listView1, and returns each sales person with over 200 sales.

var salesPerson = {{ listView1.data }};
var highSales = salesPerson.filter(i => i.sales > 200);
return highSales;

Reference child components​

You can reference child components from the parent list view or from other child components. You use the same method (e.g., {{ componentName.value }}) to access these values as you would for any other component. You can't access a list view's child components from outside the list view. Depending on your use case, you might be able to use the list view's data instead using {{ listViewName.data }}.

Customize appearance​

You can customize the overall appearance of the List View component. Select the component and modify appearance settings like height, layout type, etc.

Retool recommends using a fixed height for List Views. If needed, you can use auto heights with server side pagination but it requires additional configuration.

Auto height configuration​

You might use auto height when your data set is less than 25 items, or when fixed heights don't otherwise fit your use case. For the latter, Retool recommends using the auto height setting with server side pagination. This requires some additional code to function.

For example, you can use a JavaScript transformer and a Page Input component to return only a subset of values from your data source. The transformer might look like this.

const currentPage = {{ pageInput1.value }} - 1
const pageSize = 5
const pageStart = currentPage * pageSize
const pageEnd = pageStart + pageSize

return {{filteredTableData.value}}.slice(pageStart, pageEnd)

You'd then set the List View's data source to this transformer and add a Page Input component to the list view. Page Input components include a Page count value that you can set manually, or you can write JavaScript to display the page count dynamically. For example, {{Math.ceil(filteredTableData.value.length / 5)}} divides the number of items returned in the transformer from above by 5 to determine the number of pages. See the demo below for a walkthrough.

Nested List Views​

note

Nested List Views are available on Retool Cloud and Self-hosted Retool v2.98.2 and later.

You can nest a List View component within another List View component. This nesting dynamically generates UI elements based on multidimensional arrays and tree-like data structures—for example, org charts or threaded comments. Nested List Views support up to three levels of depth and can also reference child components using componentName.value.

The following demo app uses two List View components. The first contains the teams: Engineering, Marketing, and Sales. The second is nested inside the first and contains the team members.

The transformedJS and transformedSql queries convert sampleData into an object you can use in a nested List View.

sampleData
return {
  name: ["Bob", "Kate", "Sarah", "Ali", "Joe", "Lisa", "Lenny"],
  team: [
    "Engineering",
    "Engineering",
    "Marketing",
    "Sales",
    "Engineering",
    "Sales",
    "Marketing",
  ],
};

To configure the demo app, the first List View component uses the transformedDataJs query as its data source. Then, {{ item.team }} is used to display the team names. The second List View's data source is set to {{ item.members }}, and {{ item } displays the members of each team. Click through the demo to view the configuration.