---
title: "useDocsShell"
description: "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."
canonical_url: "https://docs.mhaibaraai.cn/en/docs/reference/composables/use-docs-shell"
---
# 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`](https://docs.mhaibaraai.cn/en/docs/reference/composables/use-docs-navigation), the header section bar and the sidebar get no navigation data.

## Usage

```vue [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`](https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/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

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

## Return Value

| Name | Type | Description |
| --- | --- | --- |
| `nuxtUiLocale` | `ComputedRef<Locale>` | The `@nuxt/ui/locale` messages for the current locale, falling back to `en`; pass it to `UApp`'s `locale` |
| `rootNavigation` | `ComputedRef<ContentNavigationItem[]>` | Top-level section navigation, also provided to the component tree under the `'navigation'` key |
| `files` | `Ref<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`](https://docs.mhaibaraai.cn/en/docs/reference/composables/use-theme).

## 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()`](https://docs.mhaibaraai.cn/en/docs/reference/composables/use-locale-seo) separately.

## Changelog

See commit history for [layer/app/composables/useDocsShell.ts](https://github.com/mhaibaraai/movk-nuxt-docs/commits/main/layer/app/composables/useDocsShell.ts).

---

- [GitHub](https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/composables/useDocsShell.ts)


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
