List View and Legacy List View comparison

Retool released a new version of the List View component in December 2023. The previous version has continued to be available as the Legacy List View component. You can continue to use the Legacy List View component in existing apps but we recommend you switch to using the newer List View component. The newer version of List View is much more performant, has more features, and will receive updates.

Feature comparison

Learn more about the differences between Legacy List View and List View.

Feature	Legacy List View	List View
Number of instances	Set the instances property value.	Automatically generated for each array item in data.
Instance values	Reference nested values using the item index (e.g., textInput1[3].value).	Nested components cannot be referenced outside of List View. For form inputs, use instanceValues instead.
Instance keys	Item keys.	Primary keys.
Auto-height	Automatically grows with content.	Requires a suitable maxHeight value.
Show border	Yes	Nest the List View component within a container and use it to set the border.
Show drop shadow	Yes	Nest the List View component within a container and use it to set the drop shadow.
Styles and nested styles	Yes	Nest a container within List View to apply styles and nested styles.

Instance keys and values

Retool recommends using primary keys, a unique identifier, to track and restore instances within the List View.

List View is virtualized and only evaluates and renders items currently visible. This significantly improves performance. However, this also means that you can no longer directly reference nested items as they may not have been evaluated yet. Instead, you can reference instance values for forms and input components.

Appearance settings

List View supports all of the same appearance settings as Legacy List View, with the following exceptions:

• List View does not support border or drop shadow styles. Instead, nest a container within List View and configure it with a border and drop shadow.
• A List View with a heightType of auto requires a suitable maxHeight value to maintain performance. The default is 100vh and you can specify a different value to use. You should consider using the container in which List View is nested to avoid unexpected scrollbars.