> For the complete documentation index, see [llms.txt](https://docs.blynk.io/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blynk.io/en/html-widget-developer-guide/key-value-storage.md).

# Key-Value Storage

Save small JSON values that persist between sessions — user selections, widget settings, cached results — without a backend of your own.

**Where the data lives.** Storage is **local to the current user on the current browser or phone**. It is not a server-side store.

* **Web:** the browser's `localStorage`, under keys derived from the signed-in account and organization. Another browser, another device or cleared site data means the data is gone.
* **Mobile:** the app's local storage on the phone, scoped to the signed-in account.

Different users never see each other's items, and one user's items are not synced across devices. Use it for preferences and caches, never as the only copy of something that matters.

**Scopes**

| Scope      | Items are stored for                         |
| ---------- | -------------------------------------------- |
| `'device'` | The current user + the widget's bound device |
| `'org'`    | The current user + the current organization  |
| `'global'` | The current user, across every organization  |

**Keys, values and limits**

* `key` is a string of 1 to 128 characters.
* `value` is any JSON value — string, finite number, boolean, array or plain object — nested up to 15 levels (the value itself is level 1).
* `NaN`, `Infinity`, `undefined`, functions, `Date`s, `Map`s, class instances, getters, circular references and sparse arrays reject with `invalid_value`. Convert dates to timestamps or ISO strings first.
* One value may not exceed **16 KB** of compact JSON. One account may not exceed **512 KB** or **1024 items** across all scopes.
* A missing key reads back as `null`, and setting `null` removes the key — so `null` can't be stored as a value.

**Errors** — every storage method fails with a `BlynkBridgeError`:

| Code                                     | When                                                                                                                          |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `invalid_scope`                          | `scope` isn't `'device'`, `'org'` or `'global'`                                                                               |
| `invalid_key`                            | `key` isn't a string of 1 to 128 characters                                                                                   |
| `invalid_value`                          | `value` isn't a JSON value, or is nested too deeply                                                                           |
| `value_too_large`                        | The value exceeds 16 KB of compact JSON                                                                                       |
| `storage_quota_exceeded`                 | The write would exceed 512 KB / 1024 items, or the browser refused it. Nothing was written                                    |
| `session_changed`                        | The account, organization or page changed after this page loaded — stop using storage; the widget reloads for the new session |
| `organization_unavailable`               | `'org'` scope with no organization selected                                                                                   |
| `device_unavailable`                     | `'device'` scope with no bound device, or storage unavailable in this browser                                                 |
| `request_timeout`                        | Web, no answer within 10 seconds                                                                                              |
| `transport_disconnected`, `server_error` | The storage result couldn't be read, or storage failed without a specific code                                                |

### Get a stored item

> Reads a stored JSON value.

```js
bridge.getStorageItem(scope, key)  // → Promise<any | null>
```

| Name    | Type     | Required | Description                       |
| ------- | -------- | -------- | --------------------------------- |
| `scope` | `string` | yes      | `'device'`, `'org'` or `'global'` |
| `key`   | `string` | yes      | 1 to 128 characters               |

Resolves with the stored value, or `null` when the key isn't set.

### Set a stored item

> Stores a JSON value under a key.

```js
bridge.setStorageItem(scope, key, value)  // → Promise<null>
```

| Name    | Type     | Required | Description                                                    |
| ------- | -------- | -------- | -------------------------------------------------------------- |
| `scope` | `string` | yes      | `'device'`, `'org'` or `'global'`                              |
| `key`   | `string` | yes      | 1 to 128 characters                                            |
| `value` | JSON     | yes      | Any JSON value within the limits above. `null` removes the key |

### Remove a stored item

> Removes a key. Succeeds even when it wasn't set.

```js
bridge.removeStorageItem(scope, key)  // → Promise<null>
```

### Clear a storage scope

> Removes every item of a scope for the current user.

```js
bridge.clearStorage(scope)  // → Promise<null>
```

**Example**

```js
await bridge.setStorageItem('device', 'chartRange', { period: 'WEEK', showMinMax: true });

const saved = await bridge.getStorageItem('device', 'chartRange');
// → { period: 'WEEK', showMinMax: true }, or null when the key isn't set

await bridge.removeStorageItem('device', 'chartRange');
await bridge.clearStorage('device');
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.blynk.io/en/html-widget-developer-guide/key-value-storage.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
