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.
| Component | State variable(s) |
|---|---|
| Checkbox | isChecked is a boolean value |
| Select | value is a text value, corresponding to the option’s value |
| Switch | isChecked is a boolean value |
| TextInput | value 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
| Type | Description | How to type in code editor |
|---|---|---|
| Text | Self explanatory. | Type in text surrounded by single quotes ' or double quotes ", like "Hello, world!". |
| Number | Self explanatory. | Type in number, digits only, without commas or any other symbols. |
| Boolean | Either true or false. Used for components like checkboxes and switches. | Type in true or false, without quotes. |
| Array | A list of values, where the values are often of the same type. | Examples:[1, 2, 3]["a", "b", "c"]. |
| Object | A 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.
Interactions
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:
| Type | Trigger(s) | Description |
|---|---|---|
| General | onClick | When an element is clicked. |
| General | onMouseDown / onMouseUp | When the mouse primary button is down/up over an element. These triggers can be used to create more complex interactions than just onClick. |
| General | onMouseEnter / onMouseLeave | When the mouse cursor enters/leaves an element. These triggers can be used to create hover interactions. |
| Input | onChange | When an input element’s state changes. Example: Typing something in a text input, clicking a checkbox. |
| Input | onFocus | When an input element is focused (usually via clicking or tabbing). Example: Clicking on a text input focuses it. |
| Input | onBlur | When 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:
| Action | Description | Result in $steps |
|---|---|---|
| Update state | Updates a state variable in scope of the current page/component. Useful for changing content. | Updated value, or undefined if cleared. |
| Update variant | Updates 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 integration | Performs 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 page | Navigates to another page. Dynamic pages can be configued with dynamic values. Link to pages documentation | Nothing (undefined). |
| Run code | Runs custom JavaScript code. The same limitations that apply to dynamic values apply here. | Result of invoking the custom function. |
| Run element action | Runs an element’s action. See Element actions for more. | Result of invoking the element action. |
| Run interaction prop | Runs 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 data | Refreshes data queries on the current page/component. | Nothing (undefined). |
| Login | Navigates to the Plasmic login page. Only works with Plasmic auth. | Nothing (undefined). |
| Logout | Logs 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.
Have feedback on this page? Let us know on our forum.