description: >-
List widget reference

List

The List widget provides a way to iterate over a structured dataset, such as an array of objects, and display the data in vertical sections without the need for writing the code. Each list item can contain other widgets to display data or capture user input. Once you bind the data to the first item in the List widget, the subsequent items automatically update with the corresponding values from the dataset.

<VideoEmbed host="youtube" videoId="kSDSGaXhfv0" title="What’s New With the List Widget?" caption="What’s New with the List Widget?"/>

Content properties

These properties are customizable options present in the property pane of the widget, allowing users to modify the widget according to their preferences.

Data

Items string

Expected Data Structure:

[
  {
    "id": "001",
    "name": "Blue"  
  },
  {
    "id": "002",
    "name": "Green"  
  },
  {
    "id": "003",
    "name": "Red"   
  }
]

You can add dynamic data to your list by fetching data from queries or JS functions and binding the response to the Items property. For example, if you have a query named fetchData, you can bind its response to the list by adding the following snippet in the Items property:

{{fetchData.data}}

If the retrieved data is not in the desired format, you can use JavaScript to transform it before passing it to the List widget.

Example:

{{fetchData.data.users.map((user) => {
  return {
    name: user.name,
    email: user.email
    };
  });
}}

Data identifier

Pagination

Server side pagination

Total records number

onPageChange

Item selection

Default selected item

onitemClick

General

Visible boolean

{{Select1.selectedOptionValue === "Yes"}}

Animate Loading boolean

Style properties

Style properties allow you to change the look and feel of the widget.

General

Item spacing number

Color

Background Color string

Border and shadow

Border radius string

Box Shadow string

Reference properties

Reference properties enable you to access the widget's data and state using the dot operator in other widgets or JavaScript functions. They provide additional information or allow interaction with the widget programmatically.

backgroundColor string

{{List1.backgroundColor}}

currentItemsView array

{{List1.currentItemsView}}

isVisible boolean

Example:

{{List1.isVisible}}

itemSpacing number

{{List1.itemSpacing}}

listData array

{{List1.listData}}

pageNo number

{{List1.pageNo}}

pageSize number

{{List1.pageSize}}

selectedItem object

{{List1.selectedItem}}

selectedItemView object

{{List1.selectedItemView}}

triggeredItem object

{{List1.triggeredItem}}

triggeredItemView object

{{List1.triggeredItemView}}

Internal reference 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.

currentItem object

currentIndex number

currentView object

level_* object

{{level_1.currentItem.name}}

Methods

Widget property setters enable you to modify the values of widget properties at runtime, eliminating the need to manually update properties in the editor.

These methods are asynchronous and return a Promise. You can use the .then() block to ensure execution and sequencing of subsequent lines of code in Appsmith.

setVisibility (param: boolean): Promise

List1.setVisibility(true)

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.
:::

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"
      }
    }
  ]