Showing data on your pages

How to store and use values with States

September 15, 2026
How to store and use values with States

In TeleportHQ, a state is a named value that a page or component remembers and can change while a visitor uses it, for example isMenuOpen (true or false), activeTab (a number) or selectedCategory (a text). Elements can show or hide based on a state, lists can filter or sort by it, and clicks can change it. Create one from the Page settings button above the top right of the canvas (Component settings inside a component), in the State tab. States work in every TeleportHQ project, website or web app.

Before you start

  • Nothing to turn on. Page and component states work in every project. They need no advanced feature, and using them doesn't turn a website into a web app.
  • Global states (one value shared by every page and component) are different: they need a web app. See Create a global state.
  • Role. You need a role that can edit components, for example Designer. The Page settings button is hidden for other roles and in read-only projects.

Create a state for a page or component

  1. Open the page on the canvas, for example your homepage. For a component, open the component instead.
  2. Above the top right of the canvas, click Page settings (Component settings in a component).
  3. Click the State tab.

  4. Click Create new state. The New State Value panel opens beside it.

    The TeleportHQ Page settings panel on the State tab, with the Create new state button highlighted
  5. In Name, type a name, for example activeTab.
  6. Under Source, keep Static value ("Set a fixed default value").
  7. In Type, choose string (text), boolean (true or false), number, object or array (a list). For example, choose number.
  8. In Default, type the value visitors start with, for example 1.
  9. Click Create.
The TeleportHQ New State Value panel with the Name, Source, Type and Default fields and the Create button

The state appears in the table with its Name, Type, Default value and Internal value.

Fill a state from your data

Under Source, a TeleportHQ state can also start with what a data source returns, for example the five newest products:

  • Data source ("Populate from a database, API or file"): in Data Source, choose the source. Type and Default disappear: the state holds what the source returns.
    • For a database, such as the TeleportHQ database, choose the table in Collection/Table. The state holds the table's rows as a list (array).
    • For a REST API, a JavaScript list, a CSV file or a Google Sheet, the Read from field ("What the state holds from this data source") reads the source first ("Reading the data source…"), then lets you pick: All rows (CSV file, Google Sheet), Whole response (REST API, JavaScript), or a list or object inside it, for example items · list of 12 items. The state takes the type of what you pick.
  • SQL query ("Write a custom SELECT query"): choose a database and type a query, for example SELECT name, price FROM products ORDER BY price LIMIT 5. Only reading is allowed: "Only SELECT (and WITH ... SELECT) queries are allowed. INSERT, UPDATE, DELETE, and all schema changes are blocked." A query only runs on a database, so switching to SQL query after picking a REST API, JavaScript, CSV or Google Sheets source clears that pick.

Show such a state with a list. See How to show a list of items. For a state filled from a data source, the code button in its row (tooltip Edit mapping function) lets you reshape what it holds with a short JavaScript function, for example to feed a chart.

On your published site, a state filled from data is read again on every visit, so new and changed records show on the next page load, without a new publish. When a visitor opens another record of the same page, the state is read again for that record. See Do page-load workflows run again when a visitor opens another record of the same page?.

Use a state on your page

Create a global state

A TeleportHQ global state works on every page and component, for example a cartCount shown in the header. Global states need a web app.

  1. At the bottom of the left sidebar, click the Project settings cog.
  2. Under Data & code, click Global state.
  3. Click New global state, fill in the name, type and starting value, and confirm.
The TeleportHQ Global state settings of a website, titled Global state needs web app features, with the Enable Web App features button

On a website, the settings are titled Global state needs web app features ("Global state holds values every page and component can read: the signed-in user, a cart, a chosen theme.") and show Enable Web App features. See What is a web app in TeleportHQ? before you click it.

On a web app, below your own global states, Platform globals lists the built-in, read-only values your project's features provide, such as Current User or Cart. Click one to open its details ("Platform global · read-only"): How to use it and the Properties it holds.

Check that it worked

The state is listed in the State tab (or under Global states). The Internal value column holds the value the editor uses for its preview ("This is the value used inside the editor, for conditional rendering"): change it to see how elements react on the canvas. Click Preview in the bottom toolbar to try your clicks as a visitor would.

Troubleshooting

"This name is already used by another state. Local and global state names share one namespace — pick a different one." A state on this page or component, or a global state, already has that name. Choose another, for example productTab instead of activeTab.

"Select a data source", "Select what to read from the data source", "Write a SELECT query" or "Invalid query" The Data source or SQL query source isn't filled in yet, or the query has a mistake. Pick the source and what to read, or check the table and column names in the query.

"This data source returned nothing a state can hold." The source answered with nothing to keep, for example an empty response. Check the data source in the Data Sources panel, or choose another one. "Could not read this data source: …" means the source couldn't be reached.

I can't see the Page settings button Your role can't edit components, or the project is read-only. Ask the workspace owner or an admin.

My live site starts with the wrong value Visitors start with the Default value. The Internal value only changes the editor's preview.

Good to know

  • State names start with a letter or _, use letters, numbers, _ and -, and are up to 30 characters long.
  • Downloaded code: the Next.js download runs states. The HTML download keeps simple uses, such as a click that toggles a state to open a menu; anything it can't run shows as the page first loads. Global states don't work in the HTML download. See How to download your site as code.
  • Ready-made widgets such as tabs, pop-ups (modals) and collapsible text use states for you, and also work on websites.
Share

Related Articles

How to show or hide elements based on a condition

In TeleportHQ, you show an element only when a condition is true, such as "stock equals 0" or "the menu is open", by selecting it, turning on the Conditional Rendering switch near the top of the right panel and building the condition from a value, an operator and a comparison value; it works in every project, website or web app.

How to use states in a component

In TeleportHQ, open a component, create a state in Component settings → State (for example isOpen, true or false), then change it with a Change State event on an element and use it to show or hide parts of the component; states work in every project, websites included.

How to filter a list

In TeleportHQ, you filter a list by selecting an Array Mapper or CMS list bound to data, clicking + next to Filtering in the right panel, choosing a field, an operand and a value in Filtering Options and clicking Save Changes; several filters must all match, and on database lists you can switch them to OR and group them.

How to sort a list

In TeleportHQ, you sort a list by selecting an Array Mapper bound to data and either typing a field name in Sort by with asc or desc in Sort direction, or clicking + next to Sorting to add rules with Ascending or Descending; whichever you set last is the one the list uses.

What is a web app in TeleportHQ?

In TeleportHQ, a web app is a project that uses server features (workflows, user sign-in, a store, bookings, a blog or help center, an admin panel, an AI chatbot); it publishes from TeleportHQ, can't be downloaded as code, and needs a Web App slot to keep running after 7 days, while show/hide, pop-ups and browser widgets work in websites too.

How to show data from a data source on your pages

In TeleportHQ you show data on a page by binding elements to it: click the plug icon next to a field in the right panel, pick a value in the Select Dynamic Property panel and click Bind property, or use an Array Mapper to repeat a design for every item in a list.