Nuxt/docs/3.api/2.composables/use-state.md

title	description	links
useState	The useState composable creates a reactive and SSR-friendly shared state.	label icon to size Source i-simple-icons-github https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/state.ts xs

Usage

// Create a reactive state and set default value
const count = useState('counter', () => Math.round(Math.random() * 100))

:read-more{to="/docs/getting-started/state-management"}

::important Because the data inside useState will be serialized to JSON, it is important that it does not contain anything that cannot be serialized, such as classes, functions or symbols. ::

::warning useState is a reserved function name transformed by the compiler, so you should not name your own function useState. ::

::tip{icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=mv0WcBABcIk" target="_blank"} Watch a video from Alexander Lichter about why and when to use useState(). ::

Using shallowRef

If you don't need your state to be deeply reactive, you can combine useState with shallowRef. This can improve performance when your state contains large objects and arrays.

const state = useState('my-shallow-state', () => shallowRef({ deep: 'not reactive' }))
// isShallow(state) === true

Type

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

• key: A unique key ensuring that data fetching is properly de-duplicated across requests. If you do not provide a key, then a key that is unique to the file and line number of the instance of useState will be generated for you.
• init: A function that provides initial value for the state when not initiated. This function can also return a Ref.
• T: (typescript only) Specify the type of state