How to show a list of items (List / Array Mapper)

In TeleportHQ, the Array Mapper element shows a list of items from your data, like products, team members or events. Add it from Elements → List → Array Mapper, bind its Source to a table or list in a data source, then design one card inside it. TeleportHQ repeats that card once for every item. The Array Mapper works with any data source and on websites and web apps alike.

Before you start#

• Connect a data source first, for example the TeleportHQ database or a Google Sheet. See What are data sources, and which ones can I connect?

Steps#

1. Add the Array Mapper#

1. In the left sidebar, open Elements, then the Primitives tab.
2. In the List group, find Array Mapper ("Repeats a layout for every item in a data array."). Drag it onto the page, for example inside a grid container, or click it to add it.
3. Keep it selected. The right panel shows Array Mapper Settings.

2. Connect it to your data#

1. In Array Mapper Settings, next to Source, click the plug icon.
2. In the Select Dynamic Property panel, open dataSources and choose your table, for example Products.
3. Click Bind property.
4. In Context name, keep ArrayItem or type a clearer name, for example product. You use this name to bind the card's content.

The canvas shows one copy of the Array Mapper's content for every row. A Refresh button appears in the section's title bar, and Manage Data appears under Source.

3. Design one card#

1. Inside the Array Mapper, add the elements for one item, for example an image, a heading and a price text.
2. Select the heading.
3. Click the plug icon next to its text.
4. In the Select Dynamic Property panel, open your context name (for example product) and choose name.
5. Click Bind property.
6. Repeat for the image (bind its source to product → photo) and the price.

Every card now shows its own product. Styling one card styles all of them.

Check that it worked#

The canvas shows a card for each row in your table, each with different content. If all cards look identical, see Troubleshooting.

Choose which items to show#

Without pagination, the Array Mapper has Start and End fields to show part of the list:

• Start: the first item to show, counting from 0. For example 0.
• End: where to stop. -1 means "to the end". For example, Start 0 and End 3 shows the first three items.

When the Array Mapper is bound to a data source, more settings appear:

• Paginated: see How to split a long list into pages. Ticking it clears Start and End.
• Enable search: see How to add search to a list.
• Sort by, Sort direction (asc or desc) and Sorting: see How to sort a list.
• Filtering: see How to filter a list.
• UI State: see How to design loading, empty and error states.
• Caching: see the section below.

Speed up a list with caching#

A TeleportHQ Array Mapper bound to a data source can cache its results on your published site, so the page doesn't ask the database again on every visit, filter, search or page change.

1. Select the Array Mapper.
2. Under Caching, tick Cache results.
3. In Cache for, choose a time, for example 5 minutes. Custom… lets you type a number of Seconds.
4. In Store in, tick Browser, Server, or both.

For the TeleportHQ database, the cache clears itself when the table changes: the note under the settings reads "Cleared automatically whenever products changes.", and clicking the table's name opens it. For other data sources, changes may show only after the cache time runs out. A list that shows only the signed-in visitor's own rows can't use the Server cache.

Store lists made by TeleportHQ, such as a shop's Products List, come with caching on (5 minutes, Browser and Server) and pagination on.

Troubleshooting#

All cards show the same item The card's elements are bound to one row (dataSources → table → Item 1). Bind them again to the context name, for example product → name.

The list is empty on the canvas Check that Source is bound, that the table has rows, and that no filter hides them. Click Refresh to load the latest data. If a UI State override is on, turn Override State off.

New rows I added in my database don't show Click Refresh ("Fetch fresh data from the data source") in the Array Mapper Settings title bar.

Search or caching doesn't work in the editor Both only work on the published site.

Good to know#

• Manage Data ("View and manage the table data") opens the table window so you can add or fix rows without leaving the page. See How to view, add and edit records.
• You can also type a fixed list straight into Source instead of binding it.
• For a plain grid of rows and columns, a Table element can be faster. See How to show data in a table.