@nuxt/docs 0.0.0 → 3.17.1

package/3.api/1.components/12.nuxt-route-announcer.md

@@ -0,0 +1,56 @@
+---
+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
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-route-announcer.ts
+    size: xs
+---
+
+::important
+This component is available in Nuxt v3.12+.
+::
+
+## Usage
+
+Add `<NuxtRouteAnnouncer/>` in your [`app.vue`](/docs/guide/directory-structure/app) or [`layouts/`](/docs/guide/directory-structure/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.vue]
+<template>
+  <NuxtRouteAnnouncer />
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+</template>
+```
+
+## Slots
+
+You can pass custom HTML or components through the route announcer's default slot.
+
+```vue
+  <template>
+    <NuxtRouteAnnouncer>
+      <template #default="{ message }">
+        <p>{{ message }} was loaded.</p>
+      </template>
+    </NuxtRouteAnnouncer>
+  </template>
+```
+
+## Props
+
+- `atomic`: Controls if screen readers only announce changes or the entire content. Set to true for full content readouts on updates, false for changes only. (default `false`)
+- `politeness`: Sets the urgency for screen reader announcements: `off` (disable the announcement), `polite` (waits for silence), or `assertive` (interrupts immediately). (default `polite`)
+
+::callout
+This component is optional. :br
+To achieve full customization, you can implement your own one based on [its source code](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-route-announcer.ts).
+::
+
+::callout
+You can hook into the underlying announcer instance using [the `useRouteAnnouncer` composable](/docs/api/composables/use-route-announcer), which allows you to set a custom announcement message.
+::

package/3.api/1.components/13.nuxt-time.md

@@ -0,0 +1,173 @@
+---
+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
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-time.vue
+    size: xs
+---
+
+::important
+This component is available in Nuxt v3.17+.
+::
+
+The `<NuxtTime>` component lets you display dates and times in a locale-friendly format with proper `<time>` HTML semantics. It ensures consistent rendering between server and client without hydration mismatches.
+
+## Usage
+
+You can use the `<NuxtTime>` component anywhere in your app:
+
+```vue
+<template>
+  <NuxtTime :datetime="Date.now()" />
+</template>
+```
+
+## Props
+
+### `datetime`
+
+- Type: `Date | number | string`
+- Required: `true`
+
+The date and time value to display. You can provide:
+- A `Date` object
+- A timestamp (number)
+- An ISO-formatted date string
+
+```vue
+<template>
+  <NuxtTime :datetime="Date.now()" />
+  <NuxtTime :datetime="new Date()" />
+  <NuxtTime datetime="2023-06-15T09:30:00.000Z" />
+</template>
+```
+
+### `locale`
+
+- Type: `string`
+- Required: `false`
+- Default: Uses the browser or server's default locale
+
+The [BCP 47 language tag](https://datatracker.ietf.org/doc/html/rfc5646) for formatting (e.g., 'en-US', 'fr-FR', 'ja-JP'):
+
+```vue
+<template>
+  <NuxtTime :datetime="Date.now()" locale="fr-FR" />
+</template>
+```
+
+### Formatting Props
+
+The component accepts any property from the [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) options:
+
+```vue
+<template>
+  <NuxtTime 
+    :datetime="Date.now()" 
+    year="numeric"
+    month="long"
+    day="numeric"
+    hour="2-digit"
+    minute="2-digit"
+  />
+</template>
+```
+
+This would output something like: "April 22, 2025, 08:30 AM"
+
+### `relative`
+
+- Type: `boolean`
+- Required: `false`
+- Default: `false`
+
+Enables relative time formatting using the Intl.RelativeTimeFormat API:
+
+```vue
+<template>
+  <!-- Shows something like "5 minutes ago" -->
+  <NuxtTime :datetime="Date.now() - 5 * 60 * 1000" relative />
+</template>
+```
+
+### Relative Time Formatting Props
+
+When `relative` is set to `true`, the component also accepts properties from [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat):
+
+```vue
+<template>
+  <NuxtTime 
+    :datetime="Date.now() - 3 * 24 * 60 * 60 * 1000" 
+    relative 
+    numeric="auto"
+    style="long"
+  />
+</template>
+```
+
+This would output something like: "3 days ago" or "last Friday" depending on the `numeric` setting.
+
+## Examples
+
+### Basic Usage
+
+```vue
+<template>
+  <NuxtTime :datetime="Date.now()" />
+</template>
+```
+
+### Custom Formatting
+
+```vue
+<template>
+  <NuxtTime 
+    :datetime="Date.now()" 
+    weekday="long"
+    year="numeric"
+    month="short"
+    day="numeric"
+    hour="numeric"
+    minute="numeric"
+    second="numeric"
+    timeZoneName="short"
+  />
+</template>
+```
+
+### Relative Time
+
+```vue
+<template>
+  <div>
+    <p>
+      <NuxtTime :datetime="Date.now() - 30 * 1000" relative />
+      <!-- 30 seconds ago -->
+    </p>
+    <p>  
+      <NuxtTime :datetime="Date.now() - 45 * 60 * 1000" relative />
+      <!-- 45 minutes ago -->
+    </p>
+    <p>
+      <NuxtTime :datetime="Date.now() + 2 * 24 * 60 * 60 * 1000" relative />
+      <!-- in 2 days -->
+    </p>
+  </div>
+</template>
+```
+
+### With Custom Locale
+
+```vue
+<template>
+  <div>
+    <NuxtTime :datetime="Date.now()" locale="en-US" weekday="long" />
+    <NuxtTime :datetime="Date.now()" locale="fr-FR" weekday="long" />
+    <NuxtTime :datetime="Date.now()" locale="ja-JP" weekday="long" />
+  </div>
+</template>
+```

package/3.api/1.components/2.nuxt-page.md

@@ -0,0 +1,154 @@
+---
+title: "<NuxtPage>"
+description: The <NuxtPage> component is required to display pages located in the pages/ directory.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/pages/runtime/page.ts
+    size: xs
+---
+
+`<NuxtPage>` is a built-in component that comes with Nuxt. It lets you display top-level or nested pages located in the [`pages/`](/docs/guide/directory-structure/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>` includes the following components:
+
+```vue
+<template>
+  <RouterView #default="{ Component }">
+    <!-- Optional, when using transitions -->
+    <Transition>
+      <!-- Optional, when using keep-alive -->
+      <KeepAlive>
+        <Suspense>
+          <component :is="Component" />
+        </Suspense>
+      </KeepAlive>
+    </Transition>
+  </RouterView>
+</template>
+```
+
+By default, Nuxt does not enable `<Transition>` and `<KeepAlive>`. You can enable them in the nuxt.config file or by setting the `transition` and `keepalive` properties on `<NuxtPage>`. If you want to define a specific page, you can set it in `definePageMeta` in the page component.
+
+::warning
+If you enable `<Transition>` in your page component, ensure that the page has a single root element.
+::
+
+Since `<NuxtPage>` uses `<Suspense>` under the hood, the component lifecycle behavior during page changes differs from that of a typical Vue application.
+
+In a typical Vue application, a new page component is mounted **only after** the previous one has been fully unmounted. However, in Nuxt, due to how Vue `<Suspense>` is implemented, the new page component is mounted **before** the previous one is unmounted.  
+
+## Props
+
+- `name`: tells `<RouterView>` to render the component with the corresponding name in the matched route record's components option.
+  - type: `string`
+- `route`: route location that has all of its components resolved.
+  - type: `RouteLocationNormalized`
+- `pageKey`: control when the `NuxtPage` component is re-rendered.
+  - type: `string` or `function`
+- `transition`: define global transitions for all pages rendered with the `NuxtPage` component.
+  - type: `boolean` or [`TransitionProps`](https://vuejs.org/api/built-in-components#transition)
+- `keepalive`: control state preservation of pages rendered with the `NuxtPage` component.
+  - type: `boolean` or [`KeepAliveProps`](https://vuejs.org/api/built-in-components#keepalive)
+
+::tip
+Nuxt automatically resolves the `name` and `route` by scanning and rendering all Vue component files found in the `/pages` directory.
+::
+
+## Example
+
+For example, if you pass a key that never changes, the `<NuxtPage>` component will be rendered only once - when it is first mounted.
+
+```vue [app.vue]
+<template>
+  <NuxtPage page-key="static" />
+</template>
+```
+
+You can also use a dynamic key based on the current route:
+
+```html
+<NuxtPage :page-key="route => route.fullPath" />
+```
+
+::warning
+Don't use `$route` object here as it can cause problems with how `<NuxtPage>` renders pages with `<Suspense>`.
+::
+
+Alternatively, `pageKey` can be passed as a `key` value via [`definePageMeta`](/docs/api/utils/define-page-meta) from the `<script>` section of your Vue component in the `/pages` directory.
+
+```vue [pages/my-page.vue]
+<script setup lang="ts">
+definePageMeta({
+  key: route => route.fullPath
+})
+</script>
+```
+
+:link-example{to="/docs/examples/routing/pages"}
+
+## Page's Ref
+
+To get the `ref` of a page component, access it through `ref.value.pageRef`
+
+````vue [app.vue]
+<script setup lang="ts">
+const page = ref()
+
+function logFoo () {
+  page.value.pageRef.foo()
+}
+</script>
+
+<template>
+  <NuxtPage ref="page" />
+</template>
+````
+
+````vue [my-page.vue]
+<script setup lang="ts">
+const foo = () => {
+  console.log('foo method called')
+}
+
+defineExpose({
+  foo,
+})
+</script>
+````
+
+## Custom Props
+
+`<NuxtPage>` also accepts custom props that you may need to pass further down the hierarchy.
+
+For example, in the below example, the value of `foobar` will be passed to the `NuxtPage` component and then to the page components.
+
+```vue [app.vue]
+<template>
+  <NuxtPage :foobar="123" />
+</template>
+```
+
+We can access the `foobar` prop in the page component:
+
+```vue [pages/page.vue]
+<script setup lang="ts">
+const props = defineProps<{ foobar: number }>()
+
+console.log(props.foobar) // Outputs: 123
+```
+
+If you have not defined the prop with `defineProps`, any props passed down to `NuxtPage` can still be accessed directly from the page `attrs`:
+
+```vue [pages/page.vue]
+<script setup lang="ts">
+const attrs = useAttrs()
+console.log(attrs.foobar) // Outputs: 123
+</script>
+```
+
+:read-more{to="/docs/guide/directory-structure/pages"}

package/3.api/1.components/3.nuxt-layout.md

@@ -0,0 +1,156 @@
+---
+title: "<NuxtLayout>"
+description: "Nuxt provides the <NuxtLayout> component to show layouts on pages and error pages."
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-layout.ts
+    size: xs
+---
+
+You can use `<NuxtLayout />` component to activate the `default` layout on `app.vue` or `error.vue`.
+
+```vue [app.vue]
+<template>
+  <NuxtLayout>
+    some page content
+  </NuxtLayout>
+</template>
+```
+
+:read-more{to="/docs/guide/directory-structure/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 [`layouts/`](/docs/guide/directory-structure/layouts) directory.
+  - **type**: `string`
+  - **default**: `default`
+
+```vue [pages/index.vue]
+<script setup lang="ts">
+// layouts/custom.vue
+const layout = 'custom'
+</script>
+
+<template>
+  <NuxtLayout :name="layout">
+    <NuxtPage />
+  </NuxtLayout>
+</template>
+```
+
+::note
+Please note the layout name is normalized to kebab-case, so if your layout file is named `errorLayout.vue`, it will become `error-layout` when passed as a `name` property to `<NuxtLayout />`.
+::
+
+```vue [error.vue]
+<template>
+  <NuxtLayout name="error-layout">
+    <NuxtPage />
+  </NuxtLayout>
+</template>
+```
+
+::read-more{to="/docs/guide/directory-structure/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 [`layouts/`](/docs/guide/directory-structure/layouts) directory.
+  - **type**: `string`
+  - **default**: `null`
+
+## Additional Props
+
+`NuxtLayout` also accepts any additional props that you may need to pass to the layout. These custom props are then made accessible as attributes.
+
+```vue [pages/some-page.vue]
+<template>
+  <div>
+    <NuxtLayout name="custom" title="I am a custom layout">
+      <-- ... -->
+    </NuxtLayout>
+  </div>
+</template>
+```
+
+In the above example, the value of `title` will be available using `$attrs.title` in the template or `useAttrs().title` in `<script setup>` at custom.vue.
+
+```vue [layouts/custom.vue]
+<script setup lang="ts">
+const layoutCustomProps = useAttrs()
+
+console.log(layoutCustomProps.title) // I am a custom layout
+</script>
+```
+
+## Transitions
+
+`<NuxtLayout />` renders incoming content via `<slot />`, which is then wrapped around Vue’s `<Transition />` component to activate layout transition. For this to work as expected, it is recommended that `<NuxtLayout />` is **not** the root element of the page component.
+
+::code-group
+
+```vue [pages/index.vue]
+<template>
+  <div>
+    <NuxtLayout name="custom">
+      <template #header> Some header template content. </template>
+    </NuxtLayout>
+  </div>
+</template>
+```
+
+```vue [layouts/custom.vue]
+<template>
+  <div>
+    <!-- named slot -->
+    <slot name="header" />
+    <slot />
+  </div>
+</template>
+```
+
+::
+
+:read-more{to="/docs/getting-started/transitions"}
+
+## Layout's Ref
+
+To get the ref of a layout component, access it through `ref.value.layoutRef`.
+
+::code-group
+
+```vue [app.vue]
+<script setup lang="ts">
+const layout = ref()
+
+function logFoo () {
+  layout.value.layoutRef.foo()
+}
+</script>
+
+<template>
+  <NuxtLayout ref="layout">
+    default layout
+  </NuxtLayout>
+</template>
+```
+
+```vue [layouts/default.vue]
+<script setup lang="ts">
+const foo = () => console.log('foo')
+defineExpose({
+  foo
+})
+</script>
+
+<template>
+  <div>
+    default layout
+    <slot />
+  </div>
+</template>
+```
+
+::
+
+:read-more{to="/docs/guide/directory-structure/layouts"}