Skip to main content

Store Value

This function stores key-value data to access later anywhere in the app.

info

Appsmith storeValue works similar to the browser's localStorage method setItem.

How to use the StoreValue Function

Signature

storeValue(key: string, value: any, persist? = true): Promise

Arguments

Argument NameDescription
keyName of the key
valueAdd/Update the value of the given key
persistDefaults to true. True persists the key-value pair in the browser's local storage, and you can use it between sessions. A false does not persist the value and removes the key once the page refreshes or is closed.

Accessing Store Value

You can access the values from the store by referencing the key inside the store object.

{{ appsmith.store.key }}
info

Store value is asynchronous. Thus, the execution of the function doesn't happen simultaneously, so when you try to read the key from the store in the following line, it might not always give the expected result.

Reading Store Value with Async and Await

Store value is an asynchronous action, and you get some unexpected results when you try to read the key (you added) in the following line. You sometimes want to read the store value right after you set it. To achieve this, you can use async and await .

Let’s take an example where you have an API that returns a unique identifier. You wish to store its value in the appsmith store instead of calling the API repeatedly. You have a JSObject that calls the API, stores the value in store, reads the stored value, and performs operations. But when you try to read the stored value, you get the key’s value as undefined because the key doesn’t exist in the store, and your code logic fails.

export default {
getUniqueValue: async () => {
GetUniqueNameAPI.run(
() => {
storeValue("uniqueEmail", GetUniqueNameAPI.data.uniqueName);
}
)
showAlert("Success! Store value set: " + appsmith.store.uniqueEmail);
}
}

The getUniqueValue function calls an API GetUniqueNameAPI.run() ``` and stores the value in the appsmith store with a key uniqueEmail. When you try to retrieve the value for uniqueEmail in the next line, the function shows an alert Success! Store value set: ``` undefined .

A store returns undefined when the storeValue function execution is not completed.

Why was the key not available in store when you added it?

The key is not added to the store and gives undefined value as the API call is in progress.

How to handle such a scenario?

You can use async and await to ensure your key has a valid value stored in the appsmith store for such scenarios. When using the async and await keywords, execution waits for the API call to complete before moving ahead to the next line.

Let’s modify the code snippet so that the store adds a valid value.

export default {
getUniqueValue: async () => {
await GetUniqueNameAPI.run(
() => {
storeValue("uniqueEmail", GetUniqueNameAPI.data.uniqueName);
}
)
showAlert("Success! Store value set: " + appsmith.store.uniqueEmail);
}
}

The getUniqueValue function calls GetUniqueNameAPI.run() . The async block embedded in the run method adds the API response value in the appsmith store. The prefix await to the GetUniqueNameAPI call ensures that the control waits for API execution to complete and add the value to the store for the given key. You can read the value from the store for the given key once the execution moves to the next line.

The await keyword ensures that the storeValue function execution is completed and returns a valid value for the given key

Scopes

In Appsmith, two types of scopes are available for the storeValue function. The first is a persistent (persistent store), and the second is a session (session store).

info

The storeValue in Appsmith works similar to the browser's localStorage method setItem.

Persistent Store

If you store a value in the persistent store, it will remain in the store across different sessions/pages. For example, if you store a value in a persistent store, the value will be saved even if the page is reloaded.

You can set a persistent value by simply calling the store value with two parameters:

  • Key - Name of the Key
  • Value - The value for the given key

Let's see how it works:

  • Drag and drop the input widget to the canvas.
  • Select the input widget and go to the widget properties.
  • Scroll down to the Actions section, select the onTextChanged action, and toggle the JS label.
  • Copy and paste the code below, adjusting the value if needed.
info

By default, persist is set as true. Define persist = false to use a session store.

{{storeValue('one',Input1.text)}}

Here, one is the key, and Input1.text is the value.

info

The persisted state is cleared out when a user logs out.

Session Store

You can use the session store to store the value you wish to hold until the page reloads or a user closes the window.

Let's see how it works:

  • Drag and drop another input widget to the canvas.
  • Select the input widget and go to the widget properties.
  • Scroll down to the Actions section, select the onTextChanged action, and toggle the JS label.
  • Copy and paste the code below, adjusting the value if needed.
{{storeValue('two',Input2.text, false)}}
info

Session store (persist=false) is only available till the user exits the app or refreshes a page.

The GIF below demonstrates how both functions work.

Persistent vs Session Store

info

If the same key is available in the session and persisted states, the session value gets a preference.

You can see the storeValue in action or fork the app and learn more about persistent and session stores.

Clear store value

To clear the value in the store, you can set its value to undefined.

{{
storeValue("userID", undefined);
}}

Clear Persistent store value

If you want a clear persistent store value, you must define two parameters as follows:

{{
storeValue('one', undefined);
}}

Clear Session store value

If you want to clear the session store value, you must define three parameters as follows:

{{
storeValue('two', undefined, false);
}}

What's Next

Check out the app to learn more about persistent and session stores. You can fork this app to have a better understanding of it.