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

81 lines
2.5 KiB
Markdown
Raw Normal View History

2021-10-11 17:48:03 +00:00
# State
2021-11-21 12:31:44 +00:00
Nuxt provides `useState` composable to create a reactive and SSR-friendly shared state across components.
2021-10-11 17:48:03 +00:00
2021-11-21 12:31:44 +00:00
`useState` is an SSR-friendly [`ref`](https://v3.vuejs.org/api/refs-api.html#ref) replacement. Its value will be preserved after server-side rendering (during client-side hydration) and shared across all components using a unique key.
2021-10-11 17:48:03 +00:00
2021-11-16 16:12:36 +00:00
## Signature
2021-11-16 16:12:36 +00:00
```ts
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
2021-11-21 12:31:44 +00:00
* **T**: (typescript only) Specify the type of state
2021-10-11 17:48:03 +00:00
::alert{icon=👉}
2021-11-16 16:12:36 +00:00
`useState` only works during `setup` or [`Lifecycle Hooks`](https://v3.vuejs.org/guide/composition-api-lifecycle-hooks.html#lifecycle-hooks).
::
## Best practices
::alert{type=danger icon=🚨}
Never define `const state = ref()` outside of `<script setup>` or `setup()` function.<br>
Such state will be shared across all users visiting your website and can lead to memory leaks!
::
::alert{type=success icon=✅}
Instead use `const useX = () => useState('x')`
::
## Examples
2021-10-11 17:48:03 +00:00
### Basic usage
In this example, we use a component-local counter state. Any other component that uses `useState('counter')` shares the same reactive state.
2021-10-11 17:48:03 +00:00
```vue [app.vue]
<script setup>
const counter = useState('counter', () => Math.round(Math.random() * 1000))
</script>
2021-10-11 17:48:03 +00:00
<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}
2021-11-16 16:12:36 +00:00
### Advanced
2021-11-21 12:31:44 +00:00
In this example, we use a composable that detects the user's default locale from the HTTP request headers 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}
2021-10-11 17:48:03 +00:00
2021-11-16 16:12:36 +00:00
## 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>
2021-11-16 16:12:36 +00:00
<p>Current color: {{ color }}</p>
</template>
```