setItem

Summary

Adds or replaces a value for the given key.

Method of apis/web-storage/Storageapis/web-storage/Storage

Syntax

 object.setItem(key, value);

Parameters

key

Data-type

String

The name of the key (a valid UTF-16 string, including the empty string).

value

Data-type

String

The value (a valid UTF-16 string) for the key/value pair.

Return Value

No return value

Examples

The following code examples are equivalent. The first sets a key/value pair by calling setItem. The second uses array syntax to find the key in the collection. The final example uses property name syntax to set an expando property.

sessionStorage.setItem('myKey', '...');

sessionStorage['myKey'] = '...';

sessionStorage.myKey = '...';

Notes

Any valid UTF-16 string, including the empty string, is a valid key name. If key or value are not valid UTF-16 strings, the setItem method throws an error. Non-string variable types are automatically type-converted to strings, if possible. Structured data must be converted to a string before storing. This method first checks if a key/value pair with the specified key already exists in the list associated with the object. If not, a new key/value pair with the given value is added to the list. If the key/value pair already exists, the value is updated. Keys are also available as expando properties on the Storage object. If the property name does not exist, a key/value pair is created for it. If the size of the value is larger than the disk quota remaining for the storage area, an “Out of memory” exception is thrown. Attempts to read or write a secured item from script running in the context of an unsecured URL are not permitted.

Related specifications

W3C Web Storage Specification

W3C Editor’s Draft

Attributions

• Microsoft Developer Network: Windows Internet Explorer API reference Article