Assemble a repeating list of components with the List View component

Learn how to dynamically display data using a custom-built row of components.

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.

The List View component allows you to create repeatable rows of data whose look and feel you define.

The List View component is similar to a Container in that you can nest other components inside of it. You control the number of rows, which determines the number of times a component appears in a list view.

warning

Table components and modules do not support nesting within a List View.

Demo

Try out the app to see list views in action (some buttons are disabled). The app displays users in a grid view with various configuration settings.

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 rows equal to the length of your data source. Each row includes a container that you add components to for displaying data. Retool sets some default values, but you configure list views with components and use the item and i variables to display data.

The item variable

The item variable corresponds to the value of the instance 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 the instance you are in. 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.

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.

Sample data

sampleData

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

Transformed with JS

transformedJS

const aggregatedMembers = sampleData.data.reduce((aggregator, row) => {
  const nameArray = aggregator[row.team] ?? [];
  aggregator[row.team] = [...nameArray, row.name];
  return aggregator;
}, {});

return Object.entries(aggregatedMembers).map(([team, members]) => ({
  team,
  members,
}));

Transformed with SQL

select team, array(name) as members from {{sampleData.data}} group by team

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.