Nuxt/docs/content/3.docs/1.usage/2.state.md

State

Nuxt provides useState to create a globally shared state within the context.

useState is SSR-friendly ref replacement in that its value will be hydrated (preserved) after server-side rendering and is shared across all components using a unique key.

::alert{icon=⚠️} Never define const state = ref() outside of <script setup> or setup() function. Such state will be shared across all users visiting your website and can lead to memory leaks!

✅ Instead use const useX = () => useState('x') ::

Usage

Within your pages, components and plugins you can use useState.

const state = useState<T>(key: string, init?: () => T): Ref<T>

• key: A unique key ensuring that data fetching can be properly de-duplicated across requests
• init: A function that provides initial value for the state when it's not initiated
• T: (typescript only) Specify type of state

::alert{icon=👉} useState only works during setup or Lifecycle Hooks ::

Shared State

Using auto imported composables we can define global typesafe states.

export const useColor = () => useState<string>('color', () => 'pink')

<script setup>
const color = useColor() // Same as useState('color')
</script>

<template>
  Current color: {{ color }}
</template>

Example

In this example, we use a server-only plugin to find about request locale.

export const useLocale = () => useState<string>('locale', () => 'en')

export default defineNuxtPlugin((nuxtApp) => {
  const locale = useLocale()
  locale.value = nuxtApp.ssrContext?.req.headers['accept-language']?.split(',')[0]
})

<script setup>
const locale = useLocale() // Same as useState('locale')
</script>

<template>
  Current locale: {{ locale }}
</template>