Store Value

The storeValue() function saves data in the browser as key-value pairs and can be later accessed anywhere in the application.

How to use the StoreValue Function

Save value

You can store a value in the Appsmith store using the storeValue() function by passing the parameters shown in the signature.

Signature

The syntax for storeValue function is given below:

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

Arguments

Argument Name	Description
key	Name of the key.
value	The data you want to save using storeValue(). You can save any data type in the Appsmith store.
persist	Defaults to true. True persists the key-value pair in the browser's local storage, and you can use it between sessions. A false doesn't persist the value and removes the key once the page refreshes or is closed.

Example 1: if you want to store the text of an input widget, you can use the 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 example below shows how to store employees' basic information using a function inside a JSObject.

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

Access value

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

{{ appsmith.store.key }}

Example: in the example, you stored the value of input1.text. You can access this value anywhere in the application by referencing the key email:

{{appsmith.store.email}}

Modify value

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

Example: you can update the boolean value from True to False using its key isActive as shown below:

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

Remove stored values

removeValue() function clears the value of the specified key in the store.

Example: refer to the code below to remove the value with key isActive using a JSObject:

export default {
    deleteStore: () => {
        // Delete value for a particular key
        removeValue("isActive")
            }
}

Clear store

clearStore() function clears all the stored data in the Appsmith store.

clearStore()

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 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 thepersist 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 behaviour 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.

Further Reading

• Appsmith Framework