How to sort a list

In TeleportHQ, you choose the order of a list, like newest first or cheapest first, in the list's settings in the right panel. Select the list (an Array Mapper), then either type a field name in Sort by (for example created_at) and desc or asc in Sort direction, or click + next to Sorting and choose a field with Ascending or Descending. The two ways replace each other: the one you set last is the one the list uses.

Before you start#

• The list must be bound to a data source or a headless CMS. See How to show a list of items.

Sort with Sort by and Sort direction#

1. Select the list: on the canvas or in the layers tree, click it, for example Products List. The right panel shows Array Mapper Settings.
2. In Sort by, type the field's name exactly, for example created_at.
3. In Sort direction, type desc (highest, newest or Z to A first) or asc (lowest, oldest or A to Z first).

The canvas reorders the items.

Sort with sorting rules#

The Sorting row of a TeleportHQ list lets you pick fields from a list instead of typing names, and add more than one rule. It shows only while Sort by isn't linked to a value: a linked Sort by shows a purple icon and a name, such as sortBy on the product lists of a TeleportHQ store, and then the Sorting row is hidden.

To add a rule:

1. Next to Sorting, click +. The Sorting Options panel opens beside the right panel.
2. In Select type, choose the field, for example price.
3. In the second list, choose Ascending or Descending. If you choose nothing, the rule sorts ascending.
4. Click Save Changes.

The rule shows under Sorting as price, Ascending. To sort by a second field when the first one is equal, add another rule, for example name, Ascending. To remove a rule, click the × at its right.

Let visitors choose the sort order#

To add a "Sort by price" dropdown or buttons to your TeleportHQ page, bind Sort by and Sort direction to states instead of typing them:

1. Create two states on the page, for example sortField (default price) and sortOrder (default asc). See How to store and use values with States.
2. Click the plug icon next to Sort by and bind it to sortField.
3. Click the plug icon next to Sort direction and bind it to sortOrder.
4. Make your buttons change those states with a Change State event in the Events tab. See How to use states in a component.

While Sort by is bound to a state, the Sorting row is hidden.

Check that it worked#

The canvas shows the items in the new order. Click Preview in the bottom toolbar to try sort buttons, then publish to check your live site.

Troubleshooting#

The order doesn't change Check the field name in Sort by: it must match the field exactly, for example created_at, not Created at. Type Sort direction as asc or desc. The editor reads anything other than desc or descending as ascending.

There's no Sorting row The list isn't bound to a data source, Sort by is bound to a state, or every field already has a rule. On a CMS list, "Pagination, filtering and sorting are disabled for single types".

My typed Sort by value disappeared You added a Sorting rule, which replaced it. Remove the rules and type Sort by again, or keep using rules.

Good to know#

• Sorting works with filters, search and pagination: visitors see the filtered results in your chosen order, page by page.
• Empty values come last on your site. On your published site and in Preview, a list from the TeleportHQ database or PostgreSQL puts the records that have no value in the sort field after all the others, in both directions. For example, when a reader picks Reading time (longest first) on your blog, the posts without a reading time come at the end. Your store's products, blog posts and bookable items are sorted this way too.
• The canvas shows them first in a descending sort. With desc or Descending, the editor canvas lists the records with no value at the top. Click Preview to see the order visitors get.
• Empty text isn't "no value". In a required column (Nullable unticked), an emptied field holds empty text, which sorts before "A". Those records come first in an ascending sort, in the editor and on your site.
• The order is stable. In the same lists, records that share a value, for example products with the same price, always come in the same order: the list ends its order with each record's own key. A paged list never shows a record twice or skips one.
• A CMS list has the same Sorting row, with rules only.