1---
2name: state-management
3description: useState composable and SSR-friendly state management in Nuxt
4---
5 
6# State Management
7 
8Nuxt provides `useState` for SSR-friendly reactive state that persists across components.
9 
10## useState
11 
12SSR-safe replacement for `ref` that shares state across components:
13 
14```vue
15<script setup lang="ts">
16// State is shared by key 'counter' across all components
17const counter = useState('counter', () => 0)
18</script>
19 
20<template>
21  <div>
22    Counter: {{ counter }}
23    <button @click="counter++">+</button>
24    <button @click="counter--">-</button>
25  </div>
26</template>
27```
28 
29## Creating Shared State
30 
31Define reusable state composables:
32 
33```ts
34// composables/useUser.ts
35export function useUser() {
36  return useState<User | null>('user', () => null)
37}
38 
39export function useLocale() {
40  return useState('locale', () => 'en')
41}
42```
43 
44```vue
45<script setup lang="ts">
46// Same state instance everywhere
47const user = useUser()
48const locale = useLocale()
49</script>
50```
51 
52## Initializing State
53 
54Use `callOnce` to initialize state with async data:
55 
56```vue
57<script setup lang="ts">
58const config = useState('site-config')
59 
60await callOnce(async () => {
61  config.value = await $fetch('/api/config')
62})
63</script>
64```
65 
66## Best Practices
67 
68### ❌ Don't Define State Outside Setup
69 
70```ts
71// ❌ Wrong - causes memory leaks and shared state across requests
72export const globalState = ref({ user: null })
73```
74 
75### ✅ Use useState Instead
76 
77```ts
78// ✅ Correct - SSR-safe
79export const useGlobalState = () => useState('global', () => ({ user: null }))
80```
81 
82## Clearing State
83 
84```ts
85// Clear specific state
86clearNuxtState('counter')
87 
88// Clear multiple states
89clearNuxtState(['counter', 'user'])
90 
91// Clear all state (use with caution)
92clearNuxtState()
93```
94 
95## With Pinia
96 
97For complex state management, use Pinia:
98 
99```bash
100npx nuxi module add pinia
101```
102 
103```ts
104// stores/counter.ts
105export const useCounterStore = defineStore('counter', {
106  state: () => ({
107    count: 0,
108  }),
109  actions: {
110    increment() {
111      this.count++
112    },
113  },
114})
115```
116 
117```ts
118// stores/user.ts (Composition API style)
119export const useUserStore = defineStore('user', () => {
120  const user = ref<User | null>(null)
121  const isLoggedIn = computed(() => !!user.value)
122 
123  async function login(credentials: Credentials) {
124    user.value = await $fetch('/api/login', {
125      method: 'POST',
126      body: credentials,
127    })
128  }
129 
130  return { user, isLoggedIn, login }
131})
132```
133 
134```vue
135<script setup lang="ts">
136const counterStore = useCounterStore()
137const userStore = useUserStore()
138 
139// Initialize store data once
140await callOnce(async () => {
141  await userStore.fetchUser()
142})
143</script>
144```
145 
146## Advanced: Locale Example
147 
148```ts
149// composables/useLocale.ts
150export function useLocale() {
151  return useState('locale', () => useDefaultLocale().value)
152}
153 
154export function useDefaultLocale(fallback = 'en-US') {
155  const locale = ref(fallback)
156 
157  if (import.meta.server) {
158    const reqLocale = useRequestHeaders()['accept-language']?.split(',')[0]
159    if (reqLocale) locale.value = reqLocale
160  }
161  else if (import.meta.client) {
162    const navLang = navigator.language
163    if (navLang) locale.value = navLang
164  }
165 
166  return locale
167}
168```
169 
170## State Serialization
171 
172`useState` values are serialized to JSON. Avoid:
173 
174- Functions
175- Classes
176- Symbols
177- Circular references
178 
179```ts
180// ❌ Won't work
181useState('fn', () => () => console.log('hi'))
182useState('instance', () => new MyClass())
183 
184// ✅ Works
185useState('data', () => ({ name: 'John', age: 30 }))
186useState('items', () => ['a', 'b', 'c'])
187```
188 
189<!-- 
190Source references:
191- https://nuxt.com/docs/getting-started/state-management
192- https://nuxt.com/docs/api/composables/use-state
193- https://nuxt.com/docs/api/utils/clear-nuxt-state
194-->
195