How to add search to a list
In TeleportHQ, you let visitors search a list, such as a product catalog or a staff directory, by ticking Enable search on an Array Mapper or Table bound to a data source. TeleportHQ adds a search box above the list. Visitors' searches match any part of the list's text fields, whatever the upper or lower case. Try it in Preview or on your published site: while you edit, clicking the search box selects it instead of typing in it.
Before you start
- The list must be an Array Mapper or a Table bound to a data source. See How to show a list of items.
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.
- Tick Enable search. A Search element holding a Search Input is added above the list. Its placeholder names the table, for example "Search products".
- In Search debounce, keep
300or type another wait in milliseconds. It's how long TeleportHQ waits after the visitor stops typing before it searches. - Style the search box like any other input: select Search Input in the layers tree and change it in the right panel.
What the search looks at
A TeleportHQ list search looks for each typed word anywhere inside the list's text fields, and ignores upper and lower case: choc finds "Chocolate cake", and create form finds "How to create a form", because every word only has to appear somewhere in the item, in any order. On a database list it skips number, true/false and date fields, and fields whose name ends in _at or contains date.
The order of the results
A TeleportHQ list search shows the best matches first. Items whose title holds every typed word come first, then items whose short description (such as an excerpt or summary field) holds them all, then items that match only further down, such as in the article's body. Within each of those groups, the list keeps its own order, for example Your order or newest first. The title is the field TeleportHQ shows as an item's name, such as title or name.
Pre-fill the search
A TeleportHQ search box can start with a value. In Search default value, type a fixed text, or click the plug icon next to it and pick:
- a URL Param, for example
q, so you can share links like/products?q=chocolate. The page must declare the parameter first: on the page, click Page settings above the canvas, open the SEO tab and addqunder Page Params. Page Params are available in web apps. - a state, for example one that a "Show cakes" button sets.
Check that it worked
Click Preview in the bottom toolbar, type in the search box, and watch the list update. Then publish and try it on your live site.
Troubleshooting
Typing in the search box does nothing in the editor While you edit, a click on the search box selects it. Click Preview in the bottom toolbar, then type. The info icon next to Enable search says "This functionality will be observable once the project is published": your published site always runs the search.
Search doesn't work on my live site Publish again after you turn on search: settings only reach the live site when you publish. If the list has Cache results on, new records can take until the Cache for time runs out to appear in results.
A word I know is in the list isn't found The field holding it isn't searched: it's a number, true/false or date field, or its name ends in _at or contains date.
I can't find Enable search The list isn't bound to a data source. Bind the list's Source to a table first.
Good to know
- Unticking Enable search deletes the search box and everything you put inside it. Click Undo above the canvas if you didn't mean to.
- Search, filters, sorting and pagination work together. Visitors search within the filtered list, page by page; the best matches come first, and your chosen order sorts the rest.
- Tables have Enable search and Search debounce too. See How to show data in a table.