How to design loading, empty and error states
In TeleportHQ, a list bound to data has extra versions for the moments when there are no items to show: while data is loading, when the list is empty (for example, a search found nothing), and for CMS lists and items when loading fails (error). To design one, select the list, turn on Override State in its UI State row, pick the state, and edit what it shows on the canvas. Visitors see each version automatically when that moment happens.
Before you start
- You need an Array Mapper bound to data, or a CMS list or CMS item. See How to show a list of items.
Which states each TeleportHQ element has
| Element | Normal view | Other states in the UI State list | Branches in the layers tree |
|---|---|---|---|
| Array Mapper | list (the items) | empty, loading | Items, Empty, Loading |
| CMS list | the items | empty, loading, error | Success, Error, Loading |
| CMS item | the entry | loading, error | Success, Error, Loading |
Steps
- Select the list: on the canvas or in the layers tree, click it, for example Products List. The right panel shows Array Mapper Settings (or Collection Settings for a CMS list).
- Find the UI State row.
- Turn on Override State. The list below it becomes active, set to list (loading on a CMS list or CMS item).
In the list, choose the state, for example empty. The canvas now shows that state's content.
- Edit the content on the canvas. For example, change the text to "No cakes match your search" and add a button that clears the search.
- Style it like any other element.
- Turn Override State off to go back to the real data.
Each state is also a branch of the list in the layers tree (Items, Empty and Loading for an Array Mapper), so you can select and edit its elements there.
Check that it worked
With Override State on, the canvas shows your design for the chosen state. On your published site, visitors see it on their own: the loading version while data loads (also while a filter, sort or search change loads new items, but not while infinite scroll or Load more adds items below the ones shown), the empty version when nothing matches, and for CMS elements the error version when the CMS can't be reached.
Troubleshooting
My list is empty on the canvas Override State may still be on with empty or loading chosen. Turn it off.
Override State made no change on my live site That's expected. Its info icon says: "This toggle does not have any impact on production code, it is for previewing and building purposes only." It only changes what you see while designing, and it isn't saved with the project.
There's no UI State row The project is read-only for you, or the selected element isn't a list. Select the Array Mapper itself, not an item inside it.
Good to know
- Examples of good empty states: "No events scheduled yet", or "No products match your filters" with a link that clears the filters.
- Loading states are best kept light, for example grey boxes the size of your cards, or a short "Loading…" text.
- Mixed Type elements have a Default and an Error mapping instead of UI states. See How to use CMS List, CMS Item, Rich Text and Mixed Type.
- For a single empty field inside a card, show a fallback value instead. See How to show a fallback when data is missing.