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`.

```js
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`**
::

## Examples

### Basic usage

In this example, we use a component-local counter state. Any other component that uses `useState('counter')` shares the same reactive state.

```vue [app.vue]
<script setup>
const counter = useState('counter', () => Math.round(Math.random() * 1000))
</script>

<template>
  <div>
    Counter: {{ counter }}
    <button @click="counter++">
      +
    </button>
    <button @click="counter--">
      -
    </button>
  </div>
</template>
```

:button-link[Open on StackBlitz]{href="https://stackblitz.com/github/nuxt/framework/tree/main/examples/use-state?terminal=dev" blank}

### Advanced Example

In this example, we use a composable that detects the user's default locale and keeps it in a `locale` state.

:button-link[Open on StackBlitz]{href="https://stackblitz.com/github/nuxt/framework/tree/main/examples/locale?terminal=dev" blank}

## Shared State

By using [auto-imported composables](/docs/directory-structure/composables) we can define global type-safe states and import them across the app.

```ts [composables/states.ts]
export const useCounter = () => useState<number>('counter', () => 0)
export const useColor = () => useState<string>('color', () => 'pink')
```

```vue [app.vue]
<script setup>
const color = useColor() // Same as useState('color')
</script>

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