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.