Skip to main content

storeValue()

The storeValue() function stores the data in the browser's local storage as key-value pairs that represent storage objects and can be later accessed anywhere in the application.

Using the StoreValue Function

Signature​

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

Parameters​

key​

A string containing the key name that acts as a unique identifier to access the associated value.

value​

The data you want to save using storeValue(). You can save any data type in the Appsmith store.

persist​

Accepts a boolean value. The default value is true, which ensures the persistence of the key-value pair in the browser's local storage, allowing it to be used between sessions. Setting it to false prevents the value from persisting, and the key gets removed when the page is refreshed or closed.

Example 1:

If you want to store the text of an input widget, you can use storeValue() as shown below:

{{storeValue('email',input1.text)}}

Here, email is the key where the value is stored, and input1.text is the value in the input widget that's saved in the storage object.

Example 2:

You can save any data type with storeValue(). The code snippet below shows how to store employees' basic information using a function inside a JS Object. 


export default {
    writeToStore: () => {
        storeValue("isActive", true) // Boolean
        storeValue("name", "Robert") // String 
        storeValue("pin", 9929) // Number
    
    }
}

Access stored value​

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

Signature​

{{ appsmith.store.KEY_NAME }}

Example:

If you have stored a value with the key email, you can access this value anywhere in the application using the code snippet given below: 

{{appsmith.store.email}}

Modify value​

You can update the saved value in the store, by overwriting the data using its key.

Example:

If you have stored a boolean value with the key isActive, you can update the boolean value from True to False using a JS Object as shown below:


export default {
    updateStore: () => {
        if(appsmith.store.isActive === true)
            storeValue("isActive", false) 
    }
}

Store multiple values​

If you need to store many values, instead of making multiple calls to the storeValue() function, it's recommended to use an object array to store the values. All values can be assigned in a single storeValue() function as shown below:


//employee data
storeValue("user", { "name": "Bar Crouch", "email": "bar@appsmith.com", "pin": "9984"})

The below example shows how to access the name of the employee that you have stored:


//Access store using a JSobject
    export default {
    userName: () => {
        let user = appsmith.store.user.name
        return user
    }
}
//Text binding

{{appsmith.store.user.name}}

You can update the saved employee data in the storage as shown below:


//updating employee data
export default {
    complexUpdate: () => {
        let user = appsmith.store.user // { "name": "Bar Crouch", "email": "bar@appsmith.com"}
        user.email = "barty.crouch@appsmith.com"
        user.city = "Bangalore"
        storeValue("user", user)
    }
}

Storage states​

Appsmith’s storeValue() function consists of two storage states: persistent and session state.

Persistent state​

If you store value in the persistent state, it remains in the store across different sessions/pages and value is saved even if the page is reloaded. By default, the persist argument is set to true in storeValue() and so the data is saved in a persistent state.

Example:

If you don't define the value for persist argument, the value is saved in the persistent state by default.

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

The persistent state is cleared out when the user logs out.

Session state​

You can use the session state to store the value you wish to hold until the page reloads or a user closes the window. To save data in this way, add false to the persist argument in the storeValue() function.

{{storeValue('two',Input2.text, false)}}

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

info

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

Check the sample app to learn more about persistent and session states.

Asynchronous behavior of store value​

storeValue() is asynchronous, so its execution isn't dependent on another function or task. To handle this scenario, you'll have to use async/await to control the execution.

Example:

Suppose there is a JS function that calls an API that returns a unique identifier, and you want to save the value returned using storeValue().

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

When you run the function, you expect an alert success message with the value stored in the key uniqueEmail but it shows undefined. As storeValue() is asynchronous, it may execute while the API call is in progress and the value isn't saved in the storage resulting in undefined value.

To handle such a scenario, you can use async/await to ensure that the storeValue() function waits for the API call to complete execution. Example:

Modify the code to use async/await as shown below:

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

The getUniqueValue function calls GetUniqueNameAPI.run() to fetch data from the API. The prefix await to the GetUniqueNameAPI call ensures that the control waits for API execution to complete and then moves to the following line. The prefix await to the storeValue() ensures that the value gets added to the store for the given key before executing showAlert in the next line.

See also​