Components

How to use states in a component

September 15, 2026
How to use states in a component

A state in TeleportHQ is a value stored inside a component (or a page) that can change while a visitor uses your site, for example isOpen for an FAQ item. Create the state in Component settings → State, add a Change State event to an element (for example, clicking the question toggles isOpen), then show or hide parts of the component based on that state. States work in every project, websites included: there's nothing to turn on first.

Before you start

  • States don't need a web app or an advanced feature. They work in websites too.
  • States work on your published site and in downloaded code. The HTML download runs text, number and true/false states that a click changes, so a click that opens, closes or toggles something keeps working there; list and object states keep their starting value. Only click triggers run there, and a state's name must be a valid JavaScript name (letters, digits and underscores, not starting with a digit).
  • You need the Owner, Admin or Designer role.

1. Create a state

  1. Open the component, for example FaqItem.
  2. Above the top right of the canvas, click Component settings.
  3. Open the State tab.
  4. Click Create new state. The New State Value panel opens beside it.
  5. In Name, type a name, for example isOpen.
  6. In Source, keep Static value.
  7. In Type, choose boolean (true or false). The panel starts on boolean.
  8. In Default, choose false, so the answer starts closed.
  9. Click Create.
The Component settings button above a TeleportHQ component, with its Props and State tabs and the State tab highlighted

2. Change the state when a visitor clicks

  1. On the component canvas, select the element visitors click, for example the question row.
  2. In the right panel, open the Events tab.
  3. In Create Event, set Action to click.
  4. In Type, choose Change State.
  5. In Modifies, pick isOpen.
  6. In To, choose Toggle. (False and True set a fixed value.)
  7. Click Add Event.

The event appears in the Events Manager list below.

3. Show or hide part of the component with the state

  1. Select the element that should appear only when the state is true, for example the answer text.
  2. In the right panel, turn on the Conditional Rendering switch.
  3. Set the condition so the element shows when isOpen is true.

The steps for conditions are in How to show or hide elements based on a condition.

Check that it worked

  1. In the bottom toolbar, click Preview.
  2. Click the question in the preview.

The answer opens and closes. In the editor, you can check each version without clicking: select a copy of the component on a page and use the Component State section of the right panel to switch the state's value.

Troubleshooting

I can't find the Events tab The Events tab doesn't show for an element inside a copy of a component placed on a page. Open the component itself and select the element there. It's also hidden for roles that can only view the project.

I can't find Component settings Open a component first: on a page, the button reads Page settings, and its State tab holds the page's states. The button is hidden in read-only projects and for roles that can't edit components.

"This name is already used by another state. Local and global state names share one namespace — pick a different one." A state in this component or a global state already uses the name. Pick another name, for example isAnswerOpen.

"Name must start with a letter or underscore and contain only letters, digits, underscores or dashes" This appears when you rename a state in the table. Rename it, for example is_open instead of 1open. Names can be up to 30 characters.

Changing the Component State section didn't change my live site The Component State section on a copy only previews a value in the editor. It doesn't change Preview or the published site. To change the starting value for everyone, edit the state's Default in the State tab.

Good to know

  • States also work on pages, not only in components: use Page settings → State.
  • Source can also fill a state from your data. Data source ("Populate from a database, API or file"): pick the source, then in Read from choose what the state holds, All rows of a table, or Whole response (or one part of it) for an API or a file. The state's type follows what it reads. SQL query ("Write a custom SELECT query"): the type is always array. See How to store and use values with States.
  • The Internal value column in the State tab is used only inside the editor. It doesn't change your published site.
  • Global state (a value shared by every page and component) isn't in Component settings. Open it with the Project settings cog → Data & code → Global state. It only works in web apps: on a website, the panel says "Global state needs web app features" and offers Enable Web App features. See What is a web app in TeleportHQ?
Share

Related Articles

How to add editable settings to a component (props)

In TeleportHQ, open the main component, click the connect (plug) icon next to a text, image or link field and choose Create Prop (or use Component settings → Props → Create new prop); each copy of the component can then set its own value in Component Properties.

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 store and use values with States

In TeleportHQ, a state is a named value, like isMenuOpen or activeTab, that elements can read and clicks can change; you create one for a page or component from the Page settings or Component settings button above the canvas, in the State tab, and it works in every project, website or web app; global states live in Project settings and need a web app.

How to create an accordion (expand and collapse)

In TeleportHQ, you add an expand-and-collapse panel with the Accordion element from Elements → Primitives → Interactive; its Accordion settings let you choose whether it starts Open or Closed and give several accordions the same Group Name so only one stays open at a time.

What are components, and when should I use them?

A TeleportHQ component is a reusable block, like a navigation bar, footer or card, that you design once and place on many pages; when you edit the main component, every copy updates, and each copy can still show its own text, images and links.

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.