# Using Mod Variables ### Overview Mod Variables are shared across Mod Components within a Mod. For detailed information on Mod Variables, see [Using Mod Variables](/developing-mods/developer-concepts/variables-and-data-context/using-mod-variables.md) Example use cases/scenarios for Mod Variables are: * Fetching information from an API and displaying it in a Sidebar * Ensuring a Starter Brick runs only once per page * Fetching configuration/settings from an API **Triggers:** Sidebar Panels and Triggers can be configured to run on changes to Mod Variables. Set the trigger type to "Mod Variable / State Change" **Lifetime:** By default, Mod Variable values are scoped to the current frame instance. Reloading/Navigating the frame with clear the Mod Variable values. The lifetime of the Mod Variable can be configured via the [Using Mod Variables](/developing-mods/developer-concepts/variables-and-data-context/using-mod-variables.md#mod-variable-synchronization-policy) ### Setting/Assigning to a Mod Variable To assign a value to a Mod Variable, use the Assign Mod Variable Brick in the “Store/Retrieve” Category:

In the Brick Configuration, provide a Variable Name and the Value. The Value can be of any type, and you can provide a variable.

### Reading a Mod Variable To Read a Mod Variable, use the `@mod` variable in a variable or template expression. PixieBrix fills in the variable with the current value at the time the brick is run. If the Mod Variable has not been assigned yet, it’s value will be `null`:

#### **Advanced: Reading a Snapshot of Multiple Mod Variables** In certain situations, you need to use multiple associated mod variables across multiple bricks. If you access the mod variables via the `@mod` reference, the values may change between bricks, if another starter brick run has assigned to the mod variable. To read a single snapshot of all mod variables, use the "Get Shared Page State" brick to assign the mod variables to a local variable. See [Advanced: Using Page State](/developing-mods/developer-concepts/variables-and-data-context/advanced-using-page-state.md) for more information. ### Viewing Mod Variables in Data Panel To view the current Mod Variables in the Data Panel, view the "Mod Variables" tab in the Data Panel:

To view the Mod Variables at the time the brick was run, use the "Input" tab in the Data Panel, with View toggled to "Variables"

Viewing the variables at the time a brick was run

### Async Mod Variables {% hint style="info" %} Async Mod Variables are most useful when you need to handle fetching, success, and error states. For example, when fetching data via API to show in a panel. {% endhint %} Async Mod Variables keep track of a value and metadata about generating that value. Async Mod Variables have the following shape when initialized: * `isLoading`: true if the the brick is bricks are running for the first time * `isFetching`: true if the the bricks are currently running * `isSuccess` : true if the last brick run successfully returned a value * `isError`: true if the bricks threw an error, or false otherwise * `error` : the error from the most recent run, or undefined if the most recent run was successful * `data` : the data/result from the most recent run, or undefined if the most recent run was not successful * `currentData` : the data/result from the latest run, or undefined if the bricks are currently running Using the Async Mod Variables includes additional metadata as part of your variable. You can reference each of these properties to track the status of the action, such as `@mod.myVariableName.isLoading`

#### Run with Async Mod Variable The `Run with Async Mod Variable` brick runs one or more bricks asynchronously, and tracks the value using an Async Mod Variable.

Using the Run with Async Mod Variable brick to fetch data from an API and transform the result

#### Run with Cache The `Run with Cache` brick is similar to the `Run with Async Mod Variable` brick, but only re-runs the bricks if the value is stale, or the force-fetch option is true. Run with Cache has the following configuration options: * `Mod Variable Name`: the mod variable name to track the Async Mod Variable state * `Time To Live (TTL)`: the expiry for the value when generating a value * `Force Fetch`: true to force generate the value, even if the previous value is not expired Common Cache Use Cases: * Fetching settings from a Team Database, or Remote API ### Bricks that Listen for Mod Variable Changes {% hint style="warning" %} **Watch Out:** if a Mod Variable trigger modifies a mod variable, the trigger will be re-run in response to the change. The infinite recursion can slow down the page, or cause the page to crash. {% endhint %} Other bricks in PixieBrix can take advantage of Mod Variables: * Sidebar Starter Brick: can re-render on changes to Mod Variables * Display Temporary Information: can be set to re-render on changes to Mod Variable * Trigger Starter Brick: can listen for changes to Mod Variables ### Mod Variable Synchronization Policy PixieBrix supports automatically synchronizing mod variables across frames/tabs. The following synchronization modes are supported: * None: mod variable is scoped to the frame. A full navigation/redirect of the frame will cause the mod variable value to be reset * Tab: mod variable is synchronized across all frames on the tab. The value persists across navigation/redirects * Session: mod variable is synchronized across all frames/tabs for the browser profile session. The value persists until you close/restart the browser profile To set a synchronization policy, navigate to the Mod > Mod Variables sub-tab in the Page Editor. Select the synchronization policy from the Synchronization dropdown.

Assigning the Synchronization Policy for a Mod Variable

The Mod Variables sub-tab displays declared and inferred Mod Variables. To set the synchronization policy, you must first declare the mod variable. You can declare a inferred Mod Variable by clicking the `+` button. ### Example Use Cases #### Use Case: Showing API Data in a Sidebar A popular PixieBrix use case is to fetch information from an API and display it in a Sidebar Panel. We recommend the following structure for the use case to support automatic + manual fetching: 1. Trigger: with trigger Custom Event, e.g., `fetch-tasks` 2. Sidebar Panel with trigger "Mod Variable / State change" 3. Trigger: Page Load or Interval, with Emit Custom Event brick to automatically emit `fetch-tasks` Example trigger to fetch tasks and assign to Mod Variable `@mod.tasks`:

Run with Asynchronous Mod Variable to automatically track the loading, error, and success state

The Sidebar Panel can reference the asynchronous variable state, e.g., to show a loading indicator or error message:

Referencing Async Mod Variable in Text Templates to show loading, error, and success state

#### Use Case: Running a Mod Only Once To run an mod at most once, use a Mod Variable brick to track if the mod has already been run. Add a “Cancel Current Action” brick and specify the condition as `@mod.modHasRun`

Conditionally cancelling a Starter Brick run based on a Mod Variable Value

Using a mod variable. PixieBrix shows a variable warning because there’s no brick that has set the mod variable yet. Then, add a “Assign Mod Variable” brick that sets the value of the Mod Variable to true when the mod runs:

--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.pixiebrix.com/developing-mods/developer-concepts/variables-and-data-context/using-mod-variables.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.