FlutterFlow Docs
Troubleshooting GuidesDocs Feedback
Search
⌃K
Links

ListView

​
The ListView widget is used to show a large number of items as a scrollable list. ListView is an advanced version of the Column widget that automatically provides scrolling when the list of items won't fit on the screen.
You can use ListView to show the list of items either vertically or horizontally.
Listview widget

Add ListView widget

Here's an example of how you can use a ListView widget in your project:
  1. 1.
    First, Drag the ListView widget from the Layout Elements tab (in the Widget Panel)or add it directly from the widget tree.
  2. 2.
    Now you can add as many Image widgets as you can. Again drag it from the Layout Elements tab or add it directly from the widget tree.
To create a ListView widget with custom items:
  1. 1.
    First, Drag the ListView widget from the Layout Elements tab (in the Widget Panel).
  2. 2.
    Now, add the Container widget by dragging it from the same Layout Elements tab or directly from the widget tree.
  3. 3.
    Drag and drop the Row widget inside the added Container.
  4. 4.
    Add one Image widget inside the Row.
  5. 5.
    Add the Text widget inside the Row and set its Theme Text Style to Title 1 under the Text Property section from the Property Editor. Also, set its L (Left) padding to 10.
  6. 6.
    Add an IconButton widget, click the default icon Add Box Outlined + under the icon section from the Property Editor, then search and select the chevron_right_sharp icon.
At this point, you have one item added to the list. To fill the ListView with more items, copy-paste the container widget. You can also change the image inside the Image widget to make all items look different.
To copy-paste a container widget:
  1. 1.
    Select the Container widget.
  2. 2.
    Right-click on it and select Copy. You can also use the keyboard shortcut Ctrl+C or Command+C.
  3. 3.
    Select the ListView widget.
  4. 4.
    Right-click on it and select Paste. You can also use the keyboard shortcut Ctrl+V or Command+V.
After adding several items in ListView looks like this:

Showing backend data

You probably want to show a list of items from your backend. There are primarily following sources from where you can get the data.

1. Showing Data from Firestore

To show data from Firestore, create a collection, query a collection and then display the data in the Image and Text widget.
Pictures collection
Showing pictures from Firestore

2. Showing Data from API call

You may be using your own infrastructure to store your app data. The data can be retrieved via API calls.

2.1 Prerequisites

Before we show data from an API call, make sure you incorporate all the mentioned prerequisites.
  1. 1.
    Be familiar with API calls.​
  2. 2.
    ​Add API calls inside the FlutterFlow project.
If you haven't set up API calls at your backend side yet, you can use any open API to try it out. Maybe you can try this https://picsum.photos/v2/list.
After adding an API call in FlutterFlow, it looks like this:

2.2 Making API call on a ListView

Making an API call allows you to get a response (containing the list of items) and show them in the ListView.
To make an API call on a ListView:
  1. 1.
    Select the ListView widget from the widget tree or the canvas area.
  2. 2.
    Click on the Backend Query tab (on the right side of your screen).
  3. 3.
    Set the Query Type to API Call.
  4. 4.
    Set the Call Name to the API Name that fetches the data.
  5. 5.
    Click Save.

2.3 Generating Dynamic Children

Generating dynamic children help you prepare a list of items present in the API response. The returned result is stored in a variable that you can use to populate the ListView.
To generate dynamic children:
  1. 1.
    Select ListView from the widget tree or the canvas area.
  2. 2.
    Click on the Generate Dynamic Children tab (on the right side of your screen).
  3. 3.
    Enter the appropriate Variable Name.
  4. 4.
    Set the Source value to the [apicall_name] Response (from ListView).
  5. 5.
    Set the Response Options to JSON Body.
  6. 6.
    Under the Available Options, click on Unset and select the JSON Path.
  7. 7.
    Inside the JSON Path, enter the JSON expression to retrieve the list. See how to get JSON Path here.
  8. 8.
    Click Save.

2.4 Showing Data in UI Elements

To show an image from the URL stored inside the JSON key:
  1. 1.
    Select the Image widget, move to the properties panel, find the Path property and click on the Set from Variable text.
  2. 2.
    Select the [variable_name] item from the list. This should be the variable name you specified while Generating Children from Variable.
  3. 3.
    Set the Available Options to JSON Path.
  4. 4.
    Inside the JSON Path, enter the JSON expression to retrieve the image URL. See how to get JSON Path here.
  5. 5.
    Click Confirm.
  6. 6.
    Similarly, Select the Text Widget. Move to the property editor and set the data for the Text property.
Showing Data in UI Elements
Here's how it looks when you run your app:

3. Showing Data from Supabase

To show data from Supabase, create a table, query a Supabase table and then display the data in the Image and Text widget.

Adding infinite scroll

The infinite scroll automatically loads the new items as you scroll down the list. It works by showing only a limited number of items (e.g., 15, 25) at first and loads subsequent items before the user reaches the end of the list. At the end of the list, a circular progress bar is visible as the new items are loaded.
Infinite scroll
Infinite scroll behind the scene
Adding infinite scroll helps you improve the user experience by reducing the initial waiting time (as without infinite scroll, it would take more time to load the long list) and loading new items only when required.
Pro tip: Consider adding an infinite scroll if you are going to load the extensive list.
The infinite scroll can be added to the list of items retrieved from two sources:

Infinite scroll on a list from the Firestore collection

In FlutterFlow, you can directly enable the infinite scroll on a list of items received from the Firestore collection.
To enable the infinite scroll:
  1. 1.
    ​Query a collection on a ListView (skip if you have already done so).
  2. 2.
    Select the ListView, move to the properties panel and select the Backend Query section.
  3. 3.
    Scroll down the already added query and turn on the Enable Infinite Scroll.
  4. 4.
    On enabling the infinite scroll, the Listen For Changes property also gets enabled. That means the list automatically updates if changes are made to the item. This is done to keep all the items up to date on the screen. However, it does not update the list if any new item is added or deleted. In rare cases, you would need to disable this feature. To do so, turn off this property.
  5. 5.
    In infinite scroll, the items are loaded in chunks called pages. The number of items to load on a single page is determined by the Page Size property. By default, the value is set to 25 (i.e., load 25 items per page). The ListView loads the first page as soon as it is visible on the screen, and the subsequent pages (with the number of items defined in the Page Size property) are loaded as you scroll down the screen. You can adjust this value according to your design and requirement.
  6. 6.
    Click Save.
Infinite scroll on a list from the Firestore collection

Infinite scroll on a list from API call

To add an infinite scroll on the API call, you must have an endpoint that supports pagination with at least one query parameter that accepts a page number like page, offset, etc.

Pagination Variables

When you add the paginated API call in the builder and enable the infinite scroll, we provide you the following pagination variables that you can pass to your API variables. These will be available inside the Set Variable menu.
Pagination Variables
  1. 1.
    Next Page Number: You can pass this variable for the query parameter that accepts the page number. The default value is 0 and keeps increasing by one as you scroll down the list until it reaches the end.
  2. 2.
    Number of Loaded Items: This equals the number of items returned by the paginated API call.
  3. 3.
    Last Response: This is useful if you want to get anything from the last response that might help you retrieve the next set of data.
Pro tip: When passing the Number of Loaded Items for query parameters like limit, per_page, size, etc., it gives you the complete list, don't use the variable. Instead, pass a Specific Value, such as 15,20.
Adding infinite scroll includes:

1. Add paginated API call

The paginated API is the API that returns the result in chunks. Most of the paginated API requires you to add the query parameters to know how many items to retrieve and from where to start.
For example, this API call https://reqres.in/api/users?per_page=20&page=1 requires per_page parameter that specifies 20 items to load per page, and page parameter specifies to start from the first page. This is called page-based pagination.
See how to add the paginated API call by adding query parameters.

2. Passing pagination variable in API call query

This step includes adding the ListView -> ListTile widget and querying the paginated API call.
  1. 1.
    First, query and show data from API calls.
  2. 2.
    While querying the API call, pass the query parameter value from the pagination variable.
Passing pagination variable in API call query

Customizing

The Properties Panel can be used to customize the behavior of your ListView widget.

Add Padding

​Here are the instructions on how to add padding.

Showing items horizontally

In the example above, you learned how to add items vertically, a default axis for laying out children for ListView.
To show items horizontally:
  1. 1.
    Select the ListView from the widget tree or the canvas area.
  2. 2.
    Move to the Property Editor and scroll down to the ListView Properties section.
  3. 3.
    Spot the Axis dropdown, and change it to Horizontal.
In the above visual, the Axis to Horizontal is not correctly displaying. In some cases, switching the axis may require you to redesign the item.
To correct the item layout for horizontal direction:
  1. 1.
    Wrap the Row inside the Column by right-clicking on Row, select the Wrap Widget option and then click on Column. You can also select the Row widget and then hit the shortcut (⌘ + B).
  2. 2.
    Drag the Text and IconButton widget outside Row and put it inside the Column.
  3. 3.
    Set the Text widget's Theme Text Style to Body Text 1.
  4. 4.
    Drag the Row widget up and make it the first child of the Column.
  5. 5.
    Apply this to all items or simply copy-paste the modified item.
The updated item for the horizontal layout looks like this:

Shrinking the ListView

By default, the ListView widget takes up all the available space in its main axis. That means if the Axis property is set to Vertical, ListView will occupy all vertical space on the screen. Similarly, if the Axis is set to Horizontal, then ListView will reserve all the horizontal space.
To make the ListView only take the size of its children:
  1. 1.
    Select the ListView from the widget tree or the canvas area.
  2. 2.
    Move to the Property Editor and scroll down to the ListView Properties section.
  3. 3.
    Checkmark the Shrink Wrap check box.
Below you can see how the Green color selection for ListView shrinks down when Shrink Wrap is checked.

Enable Pull to Refresh

To enable pull to refresh on this widget, you can follow the instructions here.

Showing empty list widget

See how to display an empty list widget when there is no data.

Scroll to the beginning or end

See how to scroll to the beginning or end with a click of a button.

Show/Hide ListView

See how to show/hide a widget here.
Previous
Card
Next
GridView
Last modified 3mo ago