Storage: setItem() method
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
The setItem()
method of the Storage
interface, when passed a key name and value, will add that key to the given
Storage
object, or update that key's value if it already exists.
Syntax
setItem(keyName, keyValue)
Parameters
Return value
None (undefined
).
Exceptions
QuotaExceededError
DOMException
-
Thrown if the storage run out of disk quota or the user declined to grant you more space.
Examples
The following function creates three data items inside local storage.
function populateStorage() {
localStorage.setItem("bgcolor", "red");
localStorage.setItem("font", "Helvetica");
localStorage.setItem("image", "myCat.png");
}
Note: To see this used within a real-world example, see our Web Storage Demo.
Storage
only supports storing and retrieving strings. If you want to save other data types, you have to convert them to strings. For plain objects and arrays, you can use JSON.stringify()
.
const person = { name: "Alex" };
localStorage.setItem("user", person);
console.log(localStorage.getItem("user")); // "[object Object]"; not useful!
localStorage.setItem("user", JSON.stringify(person));
console.log(JSON.parse(localStorage.getItem("user"))); // { name: "Alex" }
However, there's no generic way to store arbitrary data types. Furthermore, the retrieved object is a deep copy of the original object and mutations to it do not affect the original object.
Specifications
Specification |
---|
HTML Standard # dom-storage-setitem-dev |
Browser compatibility
BCD tables only load in the browser