@nuxt/docs-nightly 4.3.0-29356103.2f7957ac → 4.3.0-29430576.f48ea4c8

package/{3.api → 4.api}/1.components/12.nuxt-route-announcer.md

@@ -1,8 +1,6 @@
 ---
 title: '<NuxtRouteAnnouncer>'
 description: 'The <NuxtRouteAnnouncer> component adds a hidden element with the page title to announce route changes to assistive technologies.'
-navigation:
-  badge: New
 links:
   - label: Source
     icon: i-simple-icons-github
@@ -16,7 +14,7 @@ This component is available in Nuxt v3.12+.
 
 ## Usage
 
-Add `<NuxtRouteAnnouncer/>` in your [`app.vue`](/docs/4.x/guide/directory-structure/app) or [`app/layouts/`](/docs/4.x/guide/directory-structure/app/layouts) to enhance accessibility by informing assistive technologies about page title changes. This ensures that navigational changes are announced to users relying on screen readers.
+Add `<NuxtRouteAnnouncer/>` in your [`app.vue`](/docs/4.x/directory-structure/app/app) or [`app/layouts/`](/docs/4.x/directory-structure/app/layouts) to enhance accessibility by informing assistive technologies about page title changes. This ensures that navigational changes are announced to users relying on screen readers.
 
 ```vue [app/app.vue]
 <template>

package/{3.api → 4.api}/1.components/13.nuxt-time.md

@@ -1,8 +1,6 @@
 ---
 title: '<NuxtTime>'
 description: 'The <NuxtTime> component displays time in a locale-friendly format with server-client consistency.'
-navigation:
-  badge: New
 links:
   - label: Source
     icon: i-simple-icons-github

package/{3.api → 4.api}/1.components/2.nuxt-page.md

@@ -8,10 +8,10 @@ links:
     size: xs
 ---
 
-`<NuxtPage>` is a built-in component that comes with Nuxt. It lets you display top-level or nested pages located in the [`app/pages/`](/docs/4.x/guide/directory-structure/app/pages) directory.
+`<NuxtPage>` is a built-in component that comes with Nuxt. It lets you display top-level or nested pages located in the [`app/pages/`](/docs/4.x/directory-structure/app/pages) directory.
 
 ::note
-`<NuxtPage>` is a wrapper around [`<RouterView>`](https://router.vuejs.org/api/interfaces/RouterViewProps.html#interface-routerviewprops) from Vue Router. It should be used instead of `<RouterView>` because the former takes additional care of internal states. Otherwise, `useRoute()` may return incorrect paths.
+`<NuxtPage>` is a wrapper around [`<RouterView>`](https://router.vuejs.org/api/interfaces/routerviewprops) from Vue Router. It should be used instead of `<RouterView>` because the former takes additional care of internal states. Otherwise, `useRoute()` may return incorrect paths.
 ::
 
 `<NuxtPage>` includes the following components:
@@ -151,4 +151,4 @@ console.log(attrs.foobar) // Outputs: 123
 </script>
 ```
 
-:read-more{to="/docs/4.x/guide/directory-structure/app/pages"}
+:read-more{to="/docs/4.x/directory-structure/app/pages"}

package/{3.api → 4.api}/1.components/3.nuxt-layout.md

@@ -18,11 +18,11 @@ You can use `<NuxtLayout />` component to activate the `default` layout on `app.
 </template>
 ```
 
-:read-more{to="/docs/4.x/guide/directory-structure/app/layouts"}
+:read-more{to="/docs/4.x/directory-structure/app/layouts"}
 
 ## Props
 
-- `name`: Specify a layout name to be rendered, can be a string, reactive reference or a computed property. It **must** match the name of the corresponding layout file in the [`app/layouts/`](/docs/4.x/guide/directory-structure/app/layouts) directory.
+- `name`: Specify a layout name to be rendered, can be a string, reactive reference or a computed property. It **must** match the name of the corresponding layout file in the [`app/layouts/`](/docs/4.x/directory-structure/app/layouts) directory.
   - **type**: `string`
   - **default**: `default`
 
@@ -51,11 +51,11 @@ Please note the layout name is normalized to kebab-case, so if your layout file
 </template>
 ```
 
-::read-more{to="/docs/4.x/guide/directory-structure/app/layouts"}
+::read-more{to="/docs/4.x/directory-structure/app/layouts"}
 Read more about dynamic layouts.
 ::
 
-- `fallback`: If an invalid layout is passed to the `name` prop, no layout will be rendered. Specify a `fallback` layout to be rendered in this scenario. It **must** match the name of the corresponding layout file in the [`app/layouts/`](/docs/4.x/guide/directory-structure/app/layouts) directory.
+- `fallback`: If an invalid layout is passed to the `name` prop, no layout will be rendered. Specify a `fallback` layout to be rendered in this scenario. It **must** match the name of the corresponding layout file in the [`app/layouts/`](/docs/4.x/directory-structure/app/layouts) directory.
   - **type**: `string`
   - **default**: `null`
 
@@ -158,4 +158,4 @@ defineExpose({
 
 ::
 
-:read-more{to="/docs/4.x/guide/directory-structure/app/layouts"}
+:read-more{to="/docs/4.x/directory-structure/app/layouts"}

package/{3.api → 4.api}/1.components/4.nuxt-link.md

@@ -244,21 +244,21 @@ export default defineNuxtConfig({
 
 ### RouterLink
 
-When not using `external`, `<NuxtLink>` supports all Vue Router's [`RouterLink` props](https://router.vuejs.org/api/interfaces/RouterLinkProps.html)
+When not using `external`, `<NuxtLink>` supports all Vue Router's [`RouterLink` props](https://router.vuejs.org/api/interfaces/routerlinkprops)
 
-- `to`: Any URL or a [route location object](https://router.vuejs.org/api/type-aliases/RouteLocation.html) from Vue Router
-- `custom`: Whether `<NuxtLink>` should wrap its content in an `<a>` element. It allows taking full control of how a link is rendered and how navigation works when it is clicked. Works the same as [Vue Router's `custom` prop](https://router.vuejs.org/api/interfaces/RouterLinkProps.html#Properties-custom)
-- `exactActiveClass`: A class to apply on exact active links. Works the same as [Vue Router's `exactActiveClass` prop](https://router.vuejs.org/api/interfaces/RouterLinkProps.html#Properties-exactActiveClass) on internal links. Defaults to Vue Router's default (`"router-link-exact-active"`)
-- `activeClass`: A class to apply on active links. Works the same as [Vue Router's `activeClass` prop](https://router.vuejs.org/api/interfaces/RouterLinkProps.html#Properties-activeClass) on internal links. Defaults to Vue Router's default (`"router-link-active"`)
-- `replace`: Works the same as [Vue Router's `replace` prop](https://router.vuejs.org/api/interfaces/RouteLocationOptions.html#Properties-replace) on internal links
-- `ariaCurrentValue`: An `aria-current` attribute value to apply on exact active links. Works the same as [Vue Router's `ariaCurrentValue` prop](https://router.vuejs.org/api/interfaces/RouterLinkProps.html#Properties-ariaCurrentValue) on internal links
+- `to`: Any URL or a [route location object](https://router.vuejs.org/api/type-aliases/routelocation) from Vue Router
+- `custom`: Whether `<NuxtLink>` should wrap its content in an `<a>` element. It allows taking full control of how a link is rendered and how navigation works when it is clicked. Works the same as [Vue Router's `custom` prop](https://router.vuejs.org/api/interfaces/routerlinkprops#custom-)
+- `exactActiveClass`: A class to apply on exact active links. Works the same as [Vue Router's `exactActiveClass` prop](https://router.vuejs.org/api/interfaces/routerlinkprops#exactActiveClass-) on internal links. Defaults to Vue Router's default (`"router-link-exact-active"`)
+- `activeClass`: A class to apply on active links. Works the same as [Vue Router's `activeClass` prop](https://router.vuejs.org/api/interfaces/routerlinkprops#activeClass-) on internal links. Defaults to Vue Router's default (`"router-link-active"`)
+- `replace`: Works the same as [Vue Router's `replace` prop](https://router.vuejs.org/api/interfaces/routelocationoptions#replace-) on internal links
+- `ariaCurrentValue`: An `aria-current` attribute value to apply on exact active links. Works the same as [Vue Router's `ariaCurrentValue` prop](https://router.vuejs.org/api/interfaces/routerlinkprops#ariaCurrentValue-) on internal links
 
 ### NuxtLink
 
 - `href`: An alias for `to`. If used with `to`, `href` will be ignored
 - `noRel`: If set to `true`, no `rel` attribute will be added to the external link
 - `external`: Forces the link to be rendered as an `<a>` tag instead of a Vue Router `RouterLink`.
-- `prefetch`: When enabled will prefetch middleware, layouts and payloads (when using [payloadExtraction](/docs/4.x/api/nuxt-config#crossoriginprefetch)) of links in the viewport. Used by the experimental [crossOriginPrefetch](/docs/4.x/api/nuxt-config#crossoriginprefetch) config.
+- `prefetch`: When enabled will prefetch middleware, layouts and payloads (when using [payloadExtraction](/docs/4.x/guide/going-further/experimental-features#payloadextraction)) of links in the viewport. Used by the experimental [crossOriginPrefetch](/docs/4.x/guide/going-further/experimental-features#crossoriginprefetch) config.
 - `prefetchOn`: Allows custom control of when to prefetch links. Possible options are `interaction` and `visibility` (default). You can also pass an object for full control, for example: `{ interaction: true, visibility: true }`. This prop is only used when `prefetch` is enabled (default) and `noPrefetch` is not set.
 - `noPrefetch`: Disables prefetching.
 - `prefetchedClass`: A class to apply to links that have been prefetched.
@@ -276,7 +276,7 @@ Defaults can be overwritten, see [overwriting defaults](/docs/4.x/api/components
 
 ### In Nuxt Config
 
-You can overwrite some `<NuxtLink>` defaults in your [`nuxt.config`](/docs/4.x/api/nuxt-config#defaults)
+You can overwrite some `<NuxtLink>` defaults in your [`nuxt.config`](/docs/4.x/guide/going-further/experimental-features#defaults)
 
 ::important
 These options will likely be moved elsewhere in the future, such as into `app.config` or into the `app/` directory.
@@ -336,8 +336,8 @@ function defineNuxtLink (options: NuxtLinkOptions): Component {}
 
 - `componentName`: A name for the component. Default is `NuxtLink`.
 - `externalRelAttribute`: A default `rel` attribute value applied on external links. Defaults to `"noopener noreferrer"`. Set it to `""` to disable
-- `activeClass`: A default class to apply on active links. Works the same as [Vue Router's `linkActiveClass` option](https://router.vuejs.org/api/interfaces/RouterOptions.html#Properties-linkActiveClass). Defaults to Vue Router's default (`"router-link-active"`)
-- `exactActiveClass`: A default class to apply on exact active links. Works the same as [Vue Router's `linkExactActiveClass` option](https://router.vuejs.org/api/interfaces/RouterOptions.html#Properties-linkExactActiveClass). Defaults to Vue Router's default (`"router-link-exact-active"`)
+- `activeClass`: A default class to apply on active links. Works the same as [Vue Router's `linkActiveClass` option](https://router.vuejs.org/api/interfaces/routeroptions#linkActiveClass-). Defaults to Vue Router's default (`"router-link-active"`)
+- `exactActiveClass`: A default class to apply on exact active links. Works the same as [Vue Router's `linkExactActiveClass` option](https://router.vuejs.org/api/interfaces/routeroptions#linkExactActiveClass-). Defaults to Vue Router's default (`"router-link-exact-active"`)
 - `trailingSlash`: An option to either add or remove trailing slashes in the `href`. If unset or not matching the valid values `append` or `remove`, it will be ignored.
 - `prefetch`: Whether or not to prefetch links by default.
 - `prefetchOn`: Granular control of which prefetch strategies to apply by default.

package/{3.api → 4.api}/1.components/5.nuxt-loading-indicator.md

@@ -10,7 +10,7 @@ links:
 
 ## Usage
 
-Add `<NuxtLoadingIndicator/>` in your [`app.vue`](/docs/4.x/guide/directory-structure/app) or [`app/layouts/`](/docs/4.x/guide/directory-structure/app/layouts).
+Add `<NuxtLoadingIndicator/>` in your [`app.vue`](/docs/4.x/directory-structure/app/app) or [`app/layouts/`](/docs/4.x/directory-structure/app/layouts).
 
 ```vue [app/app.vue]
 <template>

package/{3.api → 4.api}/1.components/6.nuxt-error-boundary.md

@@ -9,7 +9,7 @@ links:
 ---
 
 ::tip
-The `<NuxtErrorBoundary>` uses Vue's [`onErrorCaptured`](https://vuejs.org/api/composition-api-lifecycle.html#onerrorcaptured) hook under the hood.
+The `<NuxtErrorBoundary>` uses Vue's [`onErrorCaptured`](https://vuejs.org/api/composition-api-lifecycle#onerrorcaptured) hook under the hood.
 ::
 
 ## Events

package/{3.api → 4.api}/1.components/7.nuxt-welcome.md

@@ -4,7 +4,7 @@ description: The <NuxtWelcome> component greets users in new projects made from
 links:
   - label: Source
     icon: i-simple-icons-github
-    to: https://github.com/nuxt/assets/blob/main/packages/templates/templates/welcome/index.html
+    to: https://github.com/nuxt/nuxt/blob/main/packages/ui-templates/templates/welcome/index.html
     size: xs
 ---
 
@@ -21,5 +21,5 @@ Preview the `<NuxtWelcome />` component.
 ::
 
 ::tip
-This component is part of [nuxt/assets](https://github.com/nuxt/assets).
+This component is part of [`@nuxt/ui-templates`](https://github.com/nuxt/nuxt/tree/main/packages/ui-templates) package.
 ::

package/{3.api → 4.api}/2.composables/use-app-config.md

@@ -16,4 +16,4 @@ const appConfig = useAppConfig()
 console.log(appConfig)
 ```
 
-:read-more{to="/docs/4.x/guide/directory-structure/app-config"}
+:read-more{to="/docs/4.x/directory-structure/app/app-config"}

package/{3.api → 4.api}/2.composables/use-async-data.md

@@ -18,9 +18,9 @@ Within your pages, components, and plugins you can use useAsyncData to get acces
 
 ```vue [app/pages/index.vue]
 <script setup lang="ts">
-const { data, status, error, refresh, clear } = await useAsyncData(
+const { data, status, pending, error, refresh, clear } = await useAsyncData(
   'mountains',
-  () => $fetch('https://api.nuxtjs.dev/mountains'),
+  (_nuxtApp, { signal }) => $fetch('https://api.nuxtjs.dev/mountains', { signal }),
 )
 </script>
 ```
@@ -30,7 +30,7 @@ If you're using a custom useAsyncData wrapper, do not await it in the composable
 ::
 
 ::note
-`data`, `status` and `error` are Vue refs and they should be accessed with `.value` when used within the `<script setup>`, while `refresh`/`execute` and `clear` are plain functions.
+`data`, `status`, `pending` and `error` are Vue refs and they should be accessed with `.value` when used within the `<script setup>`, while `refresh`/`execute` and `clear` are plain functions.
 ::
 
 ### Watch Params
@@ -42,10 +42,11 @@ The built-in `watch` option allows automatically rerunning the fetcher function
 const page = ref(1)
 const { data: posts } = await useAsyncData(
   'posts',
-  () => $fetch('https://fakeApi.com/posts', {
+  (_nuxtApp, { signal }) => $fetch('https://fakeApi.com/posts', {
     params: {
       page: page.value,
     },
+    signal,
   }), {
     watch: [page],
   },
@@ -70,6 +71,64 @@ const { data: user } = useAsyncData(
 </script>
 ```
 
+### Make your `handler` abortable
+
+You can make your `handler` function abortable by using the `signal` provided in the second argument. This is useful for cancelling requests when they are no longer needed, such as when a user navigates away from a page. `$fetch` natively supports abort signals.
+
+```ts
+const { data, error } = await useAsyncData(
+  'users',
+  (_nuxtApp, { signal }) => $fetch('/api/users', { signal }),
+)
+
+refresh() // will actually cancel the $fetch request (if dedupe: cancel)
+refresh() // will actually cancel the $fetch request (if dedupe: cancel)
+refresh()
+
+clear() // will cancel the latest pending handler
+```
+
+You can also pass an `AbortSignal` to the `refresh`/`execute` function to cancel individual requests manually.
+
+```ts
+const { refresh } = await useAsyncData(
+  'users',
+  (_nuxtApp, { signal }) => $fetch('/api/users', { signal }),
+)
+let abortController: AbortController | undefined
+
+function handleUserAction () {
+  abortController = new AbortController()
+  refresh({ signal: abortController.signal })
+}
+
+function handleCancel () {
+  abortController?.abort() // aborts the ongoing refresh request
+}
+```
+
+If your `handler` function does not support abort signals, you can implement your own abort logic using the `signal` provided.
+
+```ts
+const { data, error } = await useAsyncData(
+  'users',
+  (_nuxtApp, { signal }) => {
+    return new Promise((resolve, reject) => {
+      signal?.addEventListener('abort', () => {
+        reject(new Error('Request aborted'))
+      })
+      return Promise.resolve(callback.call(this, yourHandler)).then(resolve, reject)
+    })
+  },
+)
+```
+
+The handler signal will be aborted when:
+
+- A new request is made with `dedupe: 'cancel'`
+- The `clear` function is called
+- The `options.timeout` duration is exceeded
+
 ::warning
 [`useAsyncData`](/docs/4.x/api/composables/use-async-data) is a reserved function name transformed by the compiler, so you should not name your own function [`useAsyncData`](/docs/4.x/api/composables/use-async-data).
 ::
@@ -116,7 +175,7 @@ You can use `useLazyAsyncData` to have the same behavior as `lazy: true` with `u
 
 ### Shared State and Option Consistency
 
-When using the same key for multiple `useAsyncData` calls, they will share the same `data`, `error` and `status` refs. This ensures consistency across components but requires option consistency.
+When using the same key for multiple `useAsyncData` calls, they will share the same `data`, `error`, `status` and `pending` refs. This ensures consistency across components but requires option consistency.
 
 The following options **must be consistent** across all calls with the same key:
 - `handler` function
@@ -135,12 +194,12 @@ The following options **can differ** without triggering warnings:
 
 ```ts
 // ❌ This will trigger a development warning
-const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
-const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })
+const { data: users1 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { deep: false })
+const { data: users2 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { deep: true })
 
 // ✅ This is allowed
-const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: true })
-const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: false })
+const { data: users1 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { immediate: true })
+const { data: users2 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { immediate: false })
 ```
 
 ::tip
@@ -159,6 +218,7 @@ Keyed state created using `useAsyncData` can be retrieved across your Nuxt appli
   - `pending`: the request is in progress
   - `success`: the request has completed successfully
   - `error`: the request has failed
+- `pending`: a `Ref<boolean>` that is `true` while the request is in progress (that is, while `status.value === 'pending'`).
 - `clear`: a function that can be used to set `data` to `undefined` (or the value of `options.default()` if provided), set `error` to `undefined`, set `status` to `idle`, and mark any currently pending requests as cancelled.
 
 By default, Nuxt waits until a `refresh` is finished before it can be executed again.
@@ -170,14 +230,16 @@ If you have not fetched data on the server (for example, with `server: false`),
 ## Type
 
 ```ts [Signature]
+export type AsyncDataHandler<ResT> = (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<ResT>
+
 export function useAsyncData<DataT, DataE> (
-  handler: (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<DataT>,
-  options?: AsyncDataOptions<DataT>
+  handler: AsyncDataHandler<DataT>,
+  options?: AsyncDataOptions<DataT>,
 ): AsyncData<DataT, DataE>
 export function useAsyncData<DataT, DataE> (
   key: MaybeRefOrGetter<string>,
-  handler: (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<DataT>,
-  options?: AsyncDataOptions<DataT>
+  handler: AsyncDataHandler<DataT>,
+  options?: AsyncDataOptions<DataT>,
 ): Promise<AsyncData<DataT, DataE>>
 
 type AsyncDataOptions<DataT> = {
@@ -206,6 +268,7 @@ type AsyncData<DataT, ErrorT> = {
   clear: () => void
   error: Ref<ErrorT | undefined>
   status: Ref<AsyncDataRequestStatus>
+  pending: Ref<boolean>
 }
 
 interface AsyncDataExecuteOptions {

package/4.api/2.composables/use-cookie.md

@@ -0,0 +1,183 @@
+---
+title: 'useCookie'
+description: useCookie is an SSR-friendly composable to read and write cookies.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/cookie.ts
+    size: xs
+---
+
+## Usage
+
+Within your pages, components, and plugins, you can use `useCookie` to read and write cookies in an SSR-friendly way.
+
+```ts
+const cookie = useCookie(name, options)
+```
+
+::note
+`useCookie` only works in the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context).
+::
+
+::tip
+The returned ref will automatically serialize and deserialize cookie values to JSON.
+::
+
+## Type
+
+```ts [Signature]
+import type { Ref } from 'vue'
+import type { CookieParseOptions, CookieSerializeOptions } from 'cookie-es'
+
+export interface CookieOptions<T = any> extends Omit<CookieSerializeOptions & CookieParseOptions, 'decode' | 'encode'> {
+  decode?(value: string): T
+  encode?(value: T): string
+  default?: () => T | Ref<T>
+  watch?: boolean | 'shallow'
+  readonly?: boolean
+}
+
+export interface CookieRef<T> extends Ref<T> {}
+
+export function useCookie<T = string | null | undefined> (
+  name: string,
+  options?: CookieOptions<T>,
+): CookieRef<T>
+```
+
+## Parameters
+
+`name`: The name of the cookie.
+
+`options`: Options to control cookie behavior. The object can have the following properties:
+
+Most of the options will be directly passed to the [cookie](https://github.com/jshttp/cookie) package.
+
+| Property      | Type                   | Default                                                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+|---------------|------------------------|----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `decode`      | `(value: string) => T` | `decodeURIComponent` + [destr](https://github.com/unjs/destr). | Custom function to decode the cookie value.  Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to decode a previously encoded cookie value into a JavaScript string or other object. <br/> **Note:** If an error is thrown from this function, the original, non-decoded cookie value will be returned as the cookie's value.                                                                                                                                                                                                                                                       |
+| `encode`      | `(value: T) => string` | `JSON.stringify` + `encodeURIComponent`                        | Custom function to encode the cookie value. Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to encode a value into a string suited for a cookie's value.                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `default`     | `() => T \| Ref<T>`    | `undefined`                                                    | Function returning the default value if the cookie does not exist.  The function can also return a `Ref`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `watch`       | `boolean \| 'shallow'` | `true`                                                         | Whether to watch for changes and update the cookie. `true` for deep watch, `'shallow'` for shallow watch, i.e. data changes for only top level properties, `false` to disable. <br/> **Note:** Refresh `useCookie` values manually when a cookie has changed with [`refreshCookie`](/docs/4.x/api/utils/refresh-cookie).                                                                                                                                                                                                                                                                                                                           |
+| `readonly`    | `boolean`              | `false`                                                        | If `true`, disables writing to the cookie.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `maxAge`      | `number`               | `undefined`                                                    | Max age in seconds for the cookie, i.e. the value for the [`Max-Age` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.2). The given number will be converted to an integer by rounding down. By default, no maximum age is set.                                                                                                                                                                                                                                                                                                                                                                                   |
+| `expires`     | `Date`                 | `undefined`                                                    | Expiration date for the cookie. By default, no expiration is set. Most clients will consider this a "non-persistent cookie" and will delete it on a condition like exiting a web browser application. <br/> **Note:** The [cookie storage model specification](https://datatracker.ietf.org/doc/html/rfc6265#section-5.3) states that if both `expires` and `maxAge` is set, then `maxAge` takes precedence, but not all clients may obey this, so if both are set, they should point to the same date and time! <br/>If neither of `expires` and `maxAge` is set, the cookie will be session-only and removed when the user closes their browser. |
+| `httpOnly`    | `boolean`              | `false`                                                        | Sets the HttpOnly attribute. <br/> **Note:** Be careful when setting this to `true`, as compliant clients will not allow client-side JavaScript to see the cookie in `document.cookie`.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `secure`      | `boolean`              | `false`                                                        | Sets the [`Secure` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.5). <br/>**Note:** Be careful when setting this to `true`, as compliant clients will not send the cookie back to the server in the future if the browser does not have an HTTPS connection. This can lead to hydration errors.                                                                                                                                                                                                                                                                                                                |
+| `partitioned` | `boolean`              | `false`                                                        | Sets the [`Partitioned` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/html/draft-cutler-httpbis-partitioned-cookies#section-2.1). <br/>**Note:** This is an attribute that has not yet been fully standardized, and may change in the future. <br/>This also means many clients may ignore this attribute until they understand it.<br/>More information can be found in the [proposal](https://github.com/privacycg/CHIPS).                                                                                                                                                                                                            |
+| `domain`      | `string`               | `undefined`                                                    | Sets the [`Domain` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.3). By default, no domain is set, and most clients will consider applying the cookie only to the current domain.                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `path`        | `string`               | `'/'`                                                          | Sets the [`Path` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.4). By default, the path is considered the ["default path"](https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.4).                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `sameSite`    | `boolean \| string`    | `undefined`                                                    | Sets the [`SameSite` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7). <br/>- `true` will set the `SameSite` attribute to `Strict` for strict same-site enforcement.<br/>- `false` will not set the `SameSite` attribute.<br/>- `'lax'` will set the `SameSite` attribute to `Lax` for lax same-site enforcement.<br/>- `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.<br/>- `'strict'` will set the `SameSite` attribute to `Strict` for strict same-site enforcement.                                                                    |
+
+## Return Values
+
+Returns a Vue `Ref<T>` representing the cookie value. Updating the ref will update the cookie (unless `readonly` is set). The ref is SSR-friendly and will work on both client and server.
+
+## Examples
+
+### Basic Usage
+
+The example below creates a cookie called `counter`. If the cookie doesn't exist, it is initially set to a random value. Whenever we update the `counter` variable, the cookie will be updated accordingly.
+
+```vue [app/app.vue]
+<script setup lang="ts">
+const counter = useCookie('counter')
+
+counter.value ||= Math.round(Math.random() * 1000)
+</script>
+
+<template>
+  <div>
+    <h1>Counter: {{ counter || '-' }}</h1>
+    <button @click="counter = null">
+      reset
+    </button>
+    <button @click="counter--">
+      -
+    </button>
+    <button @click="counter++">
+      +
+    </button>
+  </div>
+</template>
+```
+
+### Readonly Cookies
+
+```vue
+<script setup lang="ts">
+const user = useCookie(
+  'userInfo',
+  {
+    default: () => ({ score: -1 }),
+    watch: false,
+  },
+)
+
+if (user.value) {
+  // the actual `userInfo` cookie will not be updated
+  user.value.score++
+}
+</script>
+
+<template>
+  <div>User score: {{ user?.score }}</div>
+</template>
+```
+
+### Writable Cookies
+
+```vue
+<script setup lang="ts">
+const list = useCookie(
+  'list',
+  {
+    default: () => [],
+    watch: 'shallow',
+  },
+)
+
+function add () {
+  list.value?.push(Math.round(Math.random() * 1000))
+  // list cookie won't be updated with this change
+}
+
+function save () {
+  // the actual `list` cookie will be updated
+  list.value &&= [...list.value]
+}
+</script>
+
+<template>
+  <div>
+    <h1>List</h1>
+    <pre>{{ list }}</pre>
+    <button @click="add">
+      Add
+    </button>
+    <button @click="save">
+      Save
+    </button>
+  </div>
+</template>
+```
+
+### Cookies in API Routes
+
+You can use `getCookie` and `setCookie` from [`h3`](https://github.com/h3js/h3) package to set cookies in server API routes.
+
+```ts [server/api/counter.ts]
+export default defineEventHandler((event) => {
+  // Read counter cookie
+  let counter = getCookie(event, 'counter') || 0
+
+  // Increase counter cookie by 1
+  setCookie(event, 'counter', ++counter)
+
+  // Send JSON response
+  return { counter }
+})
+```
+
+:link-example{to="/docs/4.x/examples/advanced/use-cookie"}