Skip to main content

List

The List widget provides a way to iterate over a structured dataset (array of objects) and display the data in sections that repeat vertically without writing any code. Each list item can contain other widgets to display data or capture user input.

How to use List Widget

List components

Typically, a List widget is a collection of other widgets you can embed to display data or capture user input. When you drag a List widget on the canvas, it has Image and Text widgets embedded by default. You can add more widgets per your requirement on the first list item container. When you connect the dataset to the List and bind the data to each widget within the first list item, the widgets in the subsequent list items are updated with values from the dataset automatically.

Display data in list items

The Items property accepts data as an array of objects and can bind your dataset to the List widget. You can bind static or dynamic data generated by executing a query or a JS function.

Static data mapping

You can display static JSON data in the Items property for generating the list items.

Example: see the JSON snippet below; a collection of books has details like bookId, bookName, and price.

[
{
"bookId": "001",
"bookName": "Artificial Intelligence for Business Leaders",
"bookImage": "https://m.media-amazon.com/images/I/511Y1LSr0JL.jpg",
"price": "INR 599"
},
{
"bookId": "002",
"bookName": "Bootstrap 4 Quick Start",
"bookImage": "https://images-na.ssl-images-amazon.com/images/I/41GTBaVKAyL._SX404_BO1,204,203,200_.jpg",
"price": "INR 439.90
}
]

Add three Text widgets and one Image widget in the first list item to display the data in the List widget.

Follow the steps below to bind each JSON field to the widgets embedded in the List:

  • Select the Image widget and add {{currentItem.bookImage}} under Image property. currentItem refers to the data for a particular item. All the list items get populated based on the corresponding data in the JSON object.
  • You can now see the image in the list item, as the image widget renders the image available on the URL supplied in JSON.

Similarly, you can bind bookName, bookId, and price to the Text widgets in the first list item.

Dynamic data mapping

If you want to bind the response from a query or a JS function, then you can use mustache syntax {{ }}. Use the format of {{QUERY_NAME.data}} to bind the data returned by the query. For example, You a query GetAllEmployees, bind the response in the Items property as shown below:

{{GetAllEmployees.data}}

To learn how to bind data from JS functions, see Display Data from JS function

To display the data in individual widgets in the list item cards, use the currentItem property to bind the corresponding value from the object's fields in the widget as shown below.

{{currentItem.<attribute_or_column_name>}}

where currentItem for the first list item reflects the 0th object in the dataset. This can be used anywhere within a widget that's placed inside the List widget.

Unique list item identifier

The List widget needs to identify each item uniquely to update, reorder, add or remove them. Similar to the Primary Key concept in the database or key in React, an identifier should be selected from the Data identifier property dropdown whose values are unique in the dataset provided to the List widget.

In the preceding example, the identifier bookId has a unique value in the dataset.

If no such unique identifier is present in the data, you can join multiple identifiers to form a unique pattern by enabling the JS mode in the property.

Example:

{{currentItem.bookName + "_" + currentItem.author}}
tip

Always set the Data Identifier property with a valid unique identifier to boost performance.

Server-side pagination

Lists are often required to display large data sets from queries, but browsers can only sometimes load all the data in the database or might do so slowly. You can use server-side pagination when a client receives only a subset of data from large datasets. It allows you to define the data limit that a query call can render, thus enabling you to paginate the data and determine the pagination boundaries.

Follow the steps below to paginate the responses and request smaller chunks of data at a time:

  1. Enable the Server Side Pagination property for the List.
  2. Call the query on the onPageChange event listener.
  3. Set the LIMIT and OFFSET clauses in the query using the pageSize and pageNo properties of the List as shown below:
SELECT * FROM users LIMIT {{ <listName>.pageSize }} OFFSET {{ (<listName>.pageNo - 1) * <listName>.pageSize }}

Access list items

  • You can reference the values of each field inside the array dataset bound to the List for the selected list item using the selectedItem as shown below:


    {{<listName>.selectedItem.<fieldName>}}

    Example - In the preceding example, if you want to display the book name of the selected item in a Text widget, bind it in the Text property of the Text widget as shown below


    {{<listName>.selectedItem.bookName}}
  • You can access the sibling widgets inside a list item card using the currentView property.

    Example - If you have an Input widget and a Button widget inside the List and want to use the Input's Text property to show an alert message on button click. In the button widget's onClick event, you can access the input widget's value as shown below

    {{showAlert(currentView.<inputName>.text)}}

    The currentView property should always be used to access sibling data instead of referencing it directly Eg: {{Input1.text} may seem to work in the app's Edit mode but won't work when deployed.

  • The currentItemsView helps you to view the data and the state of the widgets present in all the items of the List widget and is an array of objects with each widget's state represented as an object. The array of objects is limited to the number of items visible on the page rather than the number list items present. If there are 300 objects in the list data, but the List widget is showing 5 items per page, then the currentItemsView property shows an array of only 5 objects.

    Example - Below is an example of the evaluated value for all the items of the List.

    [
    {
    "Image1": {
    "image": "https://assets.appsmith.com/widgets/default.png",
    "isVisible": true
    },
    "Text2": {
    "isVisible": true,
    "text": "Blue"
    },
    "Text3": {
    "isVisible": true,
    "text": "001"
    }
    },
    {
    "Image1": {
    "image": "https://assets.appsmith.com/widgets/default.png",
    "isVisible": true
    },
    "Text2": {
    "isVisible": true,
    "text": "Green"
    },
    "Text3": {
    "isVisible": true,
    "text": "002"
    }
    },
    {
    "Image1": {
    "image": "https://assets.appsmith.com/widgets/default.png",
    "isVisible": true
    },
    "Text2": {
    "isVisible": true,
    "text": "Red"
    },
    "Text3": {
    "isVisible": true,
    "text": "003"
    }
    }
    ]

Nested lists

You can nest lists within a List widget up to three levels. The level_* property can be used to access the parent List item's data and widget properties where * represents the level number (from 1 through 3).

Suppose there is a parent list - parentList, and a child list - childList1. The widgets present in the inner list childList1 can access the values of an attribute/field in the dataset using the currentItem property of the outer list parentList as shown below:

{{level_1.currentItem.fieldName}}

You can use the currentView and currentIndex properties similarly.

Suppose there is another List widget childList2 inside childList1. The innermost list, childList2 can access two levels - level_1 and level_2. Here, level_1 represents the data and state of the topmost list widget, parentList and level_2 represents childList1.

The parent list widgets don't have access to it's child list widgets. In the preceding example, the widgets in childList1 can't use level_2 or level_3 to access the data in it child lists. Similarly, childList1 can only access level_1 and not level_2, but childList2 can access both level_1 and level_2.

Properties

Properties allow you to customize the widget, connect it to other widgets and trigger events on user actions.

Widget properties

PropertyDescription
ItemsEnables you to bind static or dynamic data as an array of objects to the widget.
Data IdentifierLike keys in React, you need to select a data identifier from your dataset, which helps uniquely identify each item. This helps the List widget identify which items are added, have changed, or are removed. You can also combine two columns or data identifiers by enabling the JS mode.
Server-side PaginationEnables you to implement server side pagination on the List widget
Total RecordsThis field displays the number of records in the source data for a list. This value is used to calculate the number of pages to be displayed when using server-side pagination. Note that this field is only visible when Server Side Pagination is enabled.
VisibleControls widget's visibility on the page. When turned off: The widget is visible when the app is published. It appears translucent when in Edit mode.
Animate LoadingWhen turned off, the widget loads without any skeletal animation. You can use a toggle switch to turn it on/off. You can also turn it off/on using javascript by enabling the JS label next to it.

Internal properties

These properties are available only to the widgets placed inside the List widget and enable you to configure the widget's properties based on the position/order of the item.

PropertyDescription
currentItemRepresents the data for a particular item.
currentIndexRepresents the index of the particular item.
currentViewRepresents the data and state of the widgets present in the current list item. This property can be used to access all sibling widgets present inside a List item card.
level_*This property is only available for nested lists where * represents the level number (from 1 through 3, where 1 refers to the outermost list). This property can be used to access the currentItem, currentView and currentIndex properties of the parent lists. Eg: {{level_1.currentItem.name}}

Reference properties

These properties can be referenced in other widgets, queries, or JS functions using the dot operator.

PropertyDescription
backgroundColorRepresents the widget's Background Color setting as a CSS color value (string).
itemSpacingReflects the vertical spacing between each item. The value can range between 0 and 16. (number).
isVisibleReflects the state of the widget's Visible setting.
currentItemsViewContains an array of objects where each object represents a widget within the list items and holds information about the widgets' state.
listDataContains an array of objects that each represent a list item and its data.
pageNoContains a number representing which page of the List is currently displayed.
pageSizeContains a number representing the number of list items that can fit on one page of the List widget.
selectedItemContains an object representing the data of the selected list item.
triggeredItemContains an object representing the data of the list item that's selected when you click the list item card or when you interact with an widget (such as a button) inside the list item
selectedItemViewContains an object representing the state of the widgets inside a list item when it's selected.
triggeredItemViewContains an object representing the state of the widgets inside a list item that's selected when you click the list item card or when you interact with a widget (such as a button) inside the list item

Style properties

You can make some formatting changes to enhance the look and feel of the widget by using styles.

PropertyDescription
Background ColorSets the background color of the widget. Accepts CSS color values.
Item SpacingAdds padding to the list cells. It accepts Pixels(px) as a unit for the gap width between list item cards. Accepts number values.
Border RadiusRounds the corners of the widget's outer edge. With JS enabled, this accepts valid CSS border-radius values.
Box ShadowCasts a drop shadow from the widget's frame. With JS enabled, this accepts valid CSS box-shadow values.

Events

When the event is triggered, these event handlers can run queries, JS code, or other supported actions.

EventDescription
onItemClickSets an action when the user clicks on one of the list items.
onPageChangeSets the action to run when the List's page changes.