useDocsShell

The site shell shared by app.vue and error.vue. It loads the navigation tree and search index for the current locale, sets the html language, direction, font and grain attributes, and provides navigation to the component tree. Call it directly only when you rewrite app.vue or error.vue.

The layer's app.vue and error.vue both start with await useDocsShell(). If you override either of them in your project, you must call it too; otherwise useDocsNavigation, the header section bar and the sidebar get no navigation data.

Usage

app/app.vue
<script setup lang="ts">
const { nuxtUiLocale, rootNavigation, files } = await useDocsShell()
</script>

<template>
  <UApp :locale="nuxtUiLocale">
    <Header />
    <NuxtLayout>
      <NuxtPage />
    </NuxtLayout>
    <Footer />

    <ClientOnly>
      <UContentSearch :files="files" :navigation="rootNavigation" />
    </ClientOnly>
  </UApp>
</template>

The example keeps only the minimal shell. The layer's app.vue also mounts the AI Chat panel, the recent pages group in ⌘K and useLocaleSeo(); start from a copy of it when rewriting.

Signature

function useDocsShell(): Promise<{
  nuxtUiLocale: ComputedRef<Locale>
  rootNavigation: ComputedRef<ContentNavigationItem[]>
  files: Ref<ContentSearchSection[] | undefined>
}>

Return Value

NameTypeDescription
nuxtUiLocaleComputedRef<Locale>The @nuxt/ui/locale messages for the current locale, falling back to en; pass it to UApp's locale
rootNavigationComputedRef<ContentNavigationItem[]>Top-level section navigation, also provided to the component tree under the 'navigation' key
filesRef<ContentSearchSection[] | undefined>Full-text search index for the current locale, lazily loaded on the client only; pass it to UContentSearch

Side Effects

Calling it registers:

  • A navigation request keyed per locale (docs-navigation-{locale}) that includes the pages' category and description fields.
  • lang and dir on <html>, data-font="sans" when theme.font is sans, and data-grain when theme.grain is on.
  • viewport and theme-color meta tags, plus the radius and black-as-primary styles from useTheme.

Notes

  • await it at the top level of <script setup>. The function finishes provide and useHead before its only await; do not add another await before calling it.
  • Multilingual SEO is not part of the shell; call useLocaleSeo() separately.

Changelog

No recent changes
Copyright © 2024 - 2026