> ## Documentation Index
> Fetch the complete documentation index at: https://empty-ad9a3406.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# api.storage

> Key-value storage with JSON serialization

## Overview

`api.storage` wraps `localStorage` with automatic JSON serialization.

## Global Storage Methods

### `storage.get(key)`

Retrieve a value. Returns `null` if not found.

```javascript theme={null}
const theme = api.storage.get('my-theme');
```

| Parameter | Type     | Description |
| --------- | -------- | ----------- |
| `key`     | `string` | Storage key |

**Returns:** `any | null`

### `storage.set(key, value)`

Store a value (auto-serialized to JSON).

```javascript theme={null}
api.storage.set('my-counter', 42);
api.storage.set('my-list', [1, 2, 3]);
api.storage.set('my-obj', { name: 'test' });
```

| Parameter | Type     | Description                                |
| --------- | -------- | ------------------------------------------ |
| `key`     | `string` | Storage key                                |
| `value`   | `any`    | Value to store (must be JSON-serializable) |

<Info>
  `storage.set()` emits a `storage:change` event automatically, so other plugins can react to storage updates.
</Info>

### `storage.remove(key)`

Delete a stored key.

```javascript theme={null}
api.storage.remove('my-counter');
```

### `storage.list()`

Returns an array of all localStorage keys.

```javascript theme={null}
const keys = api.storage.list();
// → ['board-plugins-registry', 'my-counter', ...]
```

**Returns:** `string[]`

### `storage.clear()`

Clears **all** localStorage data. Use with caution.

```javascript theme={null}
api.storage.clear();
```

<Warning>
  `storage.clear()` removes everything, including other plugins' data and the plugin registry.
</Warning>

## Plugin-Scoped Storage

These methods automatically prefix keys with `plugin:{pluginId}:`, preventing collisions between plugins. The current plugin ID is determined automatically.

### `storage.getForPlugin(pluginId, key)`

Retrieve a value scoped to a specific plugin.

```javascript theme={null}
const theme = api.storage.getForPlugin(meta.id, 'theme');
// Actually reads from localStorage key: "plugin:my-plugin:theme"
```

| Parameter  | Type     | Description                              |
| ---------- | -------- | ---------------------------------------- |
| `pluginId` | `string` | Plugin ID to scope to                    |
| `key`      | `string` | Storage key (no need to prefix manually) |

**Returns:** `any | null`

### `storage.setForPlugin(pluginId, key, value)`

Store a value scoped to a specific plugin.

```javascript theme={null}
api.storage.setForPlugin(meta.id, 'theme', 'dark');
// Actually writes to localStorage key: "plugin:my-plugin:theme"
```

| Parameter  | Type     | Description                              |
| ---------- | -------- | ---------------------------------------- |
| `pluginId` | `string` | Plugin ID to scope to                    |
| `key`      | `string` | Storage key (no need to prefix manually) |
| `value`    | `any`    | Value to store                           |

<Info>
  `setForPlugin()` emits a `storage:change` event with the `pluginId` field set, so listeners can identify which plugin changed.
</Info>

## Best Practices

<AccordionGroup>
  <Accordion icon="tag" title="Use plugin-scoped storage">
    Prefer `getForPlugin`/`setForPlugin` over manual prefixing — it's safer and cleaner:

    ```javascript theme={null}
    // ✅ Good — automatic scoping
    api.storage.setForPlugin(meta.id, 'theme', 'dark');

    // ⚠️ Works, but manual prefixing
    api.storage.set(`${meta.id}-theme`, 'dark');
    ```
  </Accordion>

  <Accordion icon="download" title="Use nullish coalescing for defaults">
    ```javascript theme={null}
    const is24h = api.storage.get('clock-24h') ?? false;
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [Storage concept](/concepts/storage) — detailed guide with examples
* [Persisting Data guide](/guides/persisting-data) — real-world patterns