Interactions and state reference

This page is intended for readers who are already familiar with interactions and state. Make sure you’ve already read the intro page first.

Built-in stateful components

The following stateful components are available in all Plasmic projects.

ComponentState variable(s)
CheckboxisChecked is a boolean value
Selectvalue is a text value, corresponding to the option’s value
SwitchisChecked is a boolean value
TextInputvalue is a text value

We have more on the way and will keep this list updated.

State variables

A state variable is data used by interactive components and pages to track its state.

State variables can be connected to UI with dynamic values and updated by interactions.

Data types

TypeDescriptionHow to type in code editor
TextSelf explanatory.Type in text surrounded by single quotes ' or double quotes ", like "Hello, world!".
NumberSelf explanatory.Type in number, digits only, without commas or any other symbols.
BooleanEither true or false. Used for components like checkboxes and switches.Type in true or false, without quotes.
ArrayA list of values, where the values are often of the same type.Examples:
[1, 2, 3]
["a", "b", "c"].
ObjectA collection of values keyed by name, where the values are often related or part of the same group.Example:
{ "Name": "Alex", "Age": 18 }.

Initial value

When configuring a state variable, the initial value is the value your state variable will start with.

After that, the state variable can only be updated by interactions.

Initial value with dynamic value

The initial value can also be set to a dynamic value. In this case, not only will your state variable start as the dynamic value, but it will also be updated as the dynamic value changes!

Interactions can still update the state variable, but the state variable will be reset to the initial value if the dynamic value changes.

External access

By default, state variables can only be used within the component or page it was added in. To allow external elements to use a state variable, toggle the “Allow external access” switch on. Choose “Read only” to allow using a state variable in external dynamic values, or “Read and write” to also allow updating a state variable from external interactions.

It’s common to allow external access when building stateful components. For example, the built-in text input component allows external elements to read and write its value state.

Usage in code editor

Suppose you have component named “My Component” with a state variable named “My Variable”. You must reference the state variable in the code editor differently, depending on the context.

Within “My Component”, the state variable is $state.myVariable.

When you insert an instance of “My Component” in another component or page, the element name defaults to the component name, so by default, the state variable is $state.myComponent.myVariable.

If you rename the “My Component” element to “my element”, the state variable is $state.myElement.myVariable.


An interaction is a sequence of actions that can be triggered by a component.

Interaction triggers

The most common interaction trigger is on click (onClick). Most built-in components support onClick interactions.

Another common interaction trigger is on user input change (onChange). This is standard on stateful components.

Here’s a list of common triggers:

GeneralonClickWhen an element is clicked.
GeneralonMouseDown / onMouseUpWhen the mouse primary button is down/up over an element. These triggers can be used to create more complex interactions than just onClick.
GeneralonMouseEnter / onMouseLeaveWhen the mouse cursor enters/leaves an element. These triggers can be used to create hover interactions.
InputonChangeWhen an input element’s state changes.
Example: Typing something in a text input, clicking a checkbox.
InputonFocusWhen an input element is focused (usually via clicking or tabbing).
Example: Clicking on a text input focuses it.
InputonBlurWhen an input element is blurred (usually via clicking outside or tabbing out).
Example: Clicking outside a text input blurs it.

For developers and advanced usage, we also support most DOM events.

Action types

The following types of actions are supported:

ActionDescriptionResult in $steps
Update stateUpdates a state variable in scope of the current page/component. Useful for changing content.Updated value, or undefined if cleared.
Update variantUpdates the variant in scope of the current page/component. Useful for changing visual design.Updated variant value, dependent on the variant type.
- Toggle: true if activated, false if deactivated
- Single-select: activated variant name (e.g. "treatmentA") or undefined if deactivated
- Multi-select: array of activated variant names (e.g. ["foo", "bar"]) or undefined if deactivated
Use integrationPerforms a data query or operation.
Link to integrations documentation
Result of the data fetch or backend operation. Refer to the integration’s documentation.
If set to continue on error, the result is the error details.
Go to pageNavigates to another page. Dynamic pages can be configued with dynamic values.
Link to pages documentation
Nothing (undefined).
Run codeRuns custom JavaScript code. The same limitations that apply to dynamic values apply here.Result of invoking the custom function.
Run element actionRuns an element’s action. See Element actions for more.Result of invoking the element action.
Run interaction propRuns an interaction that was passed in to the current page/component as a prop.Result of invoking the event handler, or undefined if event handler is not set.
Refresh dataRefreshes data queries on the current page/component.Nothing (undefined).
LoginNavigates to the Plasmic login page. Only works with Plasmic auth.Nothing (undefined).
LogoutLogs the user out. Only works with Plasmic auth.Nothing (undefined).

Conditional action

Actions can be configured to run always, never, or conditionally. By default, it’s set to “Always”, though you can change it to “Never” or “When…” with a dynamic value.

Action order

Actions are run sequentially in the displayed order. You can reorder actions by hovering over an action and dragging the left handle.

Dependent actions

You can use the special $steps object in dynamic values to reference results from a previous action.

For each previous action, a field will be available on $steps.

  • The field’s name is based on the action name (you can edit this).
  • The field’s value is the action’s result, documented above in the action types section.
Was this page helpful?

Have feedback on this page? Let us know on our forum.