---
title: "useAppStorage"
description: "A Vue composable that manages reactive localStorage or sessionStorage state with type-safe defaults, serialization, and cross-tab sync."
canonical_url: "https://core.mhaibaraai.cn/en/docs/composables/use-app-storage"
---
# useAppStorage

> A Vue composable that manages reactive localStorage or sessionStorage state with type-safe defaults, serialization, and cross-tab sync.

## Usage

`useAppStorage` is a powerful composable built on top of `@vueuse/core`'s `useStorage`, enabling safe and easy management of the browser's `localStorage` or `sessionStorage`.

It automatically handles data serialization and deserialization, and provides reactive state management.

```vue
<script setup lang="ts">
import { useAppStorage } from '@movk/core'

// Define the type for user preferences
interface UserPreferences {
  theme: 'light' | 'dark'
  language: string
  notifications: {
    email: boolean
    push: boolean
  }
}

// Create a reactive storage instance
const { state, setItem, getItem, removeItem } = useAppStorage<UserPreferences>({
  key: 'user-preferences',
  defaultValue: {
    theme: 'light',
    language: 'en',
    notifications: {
      email: true,
      push: false
    }
  },
  storage: 'localStorage', // or 'sessionStorage'
  prefix: 'my-app'
})

// Use the reactive state directly in the template or script
console.log(state.value.theme) // 'light'

// Update data
function toggleTheme() {
  setItem({
    ...state.value,
    theme: state.value.theme === 'light' ? 'dark' : 'light'
  })
}

// Update partial data
function enablePushNotifications() {
  setItem({
    ...state.value,
    notifications: {
      ...state.value.notifications,
      push: true
    }
  })
}
</script>

<template>
  <div>
    <p>Current theme: {{ state.theme }}</p>
    <button @click="toggleTheme">
      Toggle theme
    </button>
    <p>Push notifications: {{ state.notifications.push ? 'Enabled' : 'Disabled' }}</p>
    <button @click="enablePushNotifications">
      Enable push notifications
    </button>
  </div>
</template>
```

> [!NOTE]
> 
> When data read from storage cannot be parsed correctly, 
> 
> useAppStorage
> 
>  automatically falls back to 
> 
> defaultValue
> 
>  and prints a warning to the console.

## API

### `useAppStorage(config)`

Creates and returns a storage instance.

#### `config` Parameters

**key** (`string`) *required*: The unique key name for the storage item.

**defaultValue** (`T`) *required*: The default value to use when no valid value exists in storage.

**storage** (`'localStorage' | 'sessionStorage'`): The browser storage type to use. Defaults to localStorage.

**prefix** (`string`): An optional prefix prepended to the key to create a namespace and avoid key conflicts. The final key will be prefix:key. Defaults to movk.

### Returns

`useAppStorage` returns an object with the following properties:

**state** (`Ref<T>`): A reactive ref whose value stays in sync with the stored data. You can read or modify it directly.

**getItem** (`() => T`): A function that reads and returns data from storage. Returns defaultValue if the data cannot be parsed.

**setItem** (`(value: T) => void`): A function that sets a new value. The new value is serialized before being stored.

**removeItem** (`() => void`): A function that removes the item from storage.

## Changelog

See commit history for [src/composables/useAppStorage.ts](https://github.com/mhaibaraai/movk-core/commits/main/src/composables/useAppStorage.ts).

---

- [GitHub](https://github.com/mhaibaraai/movk-core/blob/main/src/composables/useAppStorage.ts)


## Sitemap

See the full [sitemap](https://core.mhaibaraai.cn/sitemap.md) for all pages.