Customization

Create a Vue file with the same name as a built-in component in your component directory to replace the header, sidebars, footer and other UI regions. This page lists the components v3 promises to keep stable, where each is mounted, and a minimal override for every one of them.
Difficulty
Advanced
View source

How overriding works

Create a component with the same name in your component directory (such as app/components/) to replace the layer's implementation. The component name comes from the file name only, so app/components/HeaderLogo.vue and app/components/header/HeaderLogo.vue both register as HeaderLogo.

To change navigation, text or colors, prefer app.config (header.nav, footer.credits, ui.colors and so on) over overriding components, see Configuration Overview.

Overrides usually rely on these auto-imported composables:

FunctionPurpose
useAppConfig()Read site config such as header.title and footer.socials
useMovkI18n()Current locale, built-in translations via t(), locale-prefixed localePath()
useHeader()Resolved header links desktopLinks / mobileLinks
useDocsNavigation()The docs navigation tree of the current locale

Override contract

The components below are the ones v3 commits to: their names, mount points and props stay stable within v3.x, and none of them take props. Components not listed (such as ThemePickerButton and HeaderToggleButton) are internal and may change between versions, so overriding them is not recommended.

ComponentMounted at
HeaderTop of every page; not rendered when the route's meta.header is false or the path starts with /examples
HeaderLogoLeft side of the header
HeaderCenterCenter of the header, desktop only
HeaderCTARight side of the header, after the search box
HeaderBodyMobile navigation drawer
HeaderBottomBelow the header, docs pages only
LanguageSwitcherRight side of the header, when i18n is enabled with more than one locale
ThemePickerRight side of the header
PageHeaderLinksRight end of the metadata row below the page lead
DocsAsideLeftTopTop of the left sidebar, only when the navigation filter is shown
DocsAsideLeftBodyBody of the left sidebar, and the docs navigation in the mobile drawer
DocsAsideRightBottomBelow the table of contents, desktop only
FooterBottom of every page; not rendered when the route's meta.footer is false or the path starts with /examples
FooterLeftLeft side of the footer
FooterRightRight side of the footer
ComponentExampleExtrasExample container of ComponentExample and ComponentCode, requires movkNuxtDocs.componentDocs, see ComponentExample

The default implementations live in layer/app/components; read the source before overriding.

Header

The header container, combining the logo, main navigation, search, theme picker, color mode and language switcher. Overriding Header changes how every header sub-component below is mounted, so only do it when you need a completely different header structure.

Header
app/components/Header.vue
<template>
  <UHeader>
    <template #left>
      <HeaderLogo />
    </template>

    <HeaderCenter />

    <template #right>
      <UContentSearchButton />
      <UColorModeButton />
    </template>

    <template #body>
      <HeaderBody />
    </template>
  </UHeader>
</template>

Shows header.avatar and the site title, linking to header.to.

HeaderLogo
app/components/HeaderLogo.vue
<script setup lang="ts">
const { localePath } = useMovkI18n()
</script>

<template>
  <NuxtLink :to="localePath('/')" class="flex items-center gap-2">
    <img src="/logo.svg" alt="" class="size-6">
    <span class="font-display text-xl font-bold">My Docs</span>
  </NuxtLink>
</template>

HeaderCenter

Desktop main navigation, rendering header.nav.

HeaderCenter
app/components/HeaderCenter.vue
<script setup lang="ts">
const { desktopLinks } = useHeader()
</script>

<template>
  <UNavigationMenu :items="desktopLinks" variant="link" />
</template>

HeaderCTA

The call-to-action area on the right of the header. By default it shows the AI entry when AI Chat is enabled and is empty otherwise.

HeaderCTA
app/components/HeaderCTA.vue
<template>
  <UButton label="Get started" to="/docs/getting-started" size="sm" class="hidden md:inline-flex" />
</template>

HeaderBody

Content of the mobile navigation drawer: numbered header.mobileNav links, followed by the sidebar navigation on docs pages.

HeaderBody
app/components/HeaderBody.vue
<script setup lang="ts">
const { mobileLinks } = useHeader()
const isDocsRoute = useDocsRoute()
</script>

<template>
  <UNavigationMenu :items="mobileLinks" orientation="vertical" />

  <DocsAsideLeftBody v-if="isDocsRoute" class="mt-6" />
</template>

HeaderBottom

The numbered section bar below the header on docs pages; its bottom line doubles as the reading progress bar. An override has to implement reading progress itself.

HeaderBottom
app/components/HeaderBottom.vue
<script setup lang="ts">
const navigation = useDocsNavigation()
</script>

<template>
  <UContainer class="hidden lg:flex gap-6 h-12 items-center border-t border-default">
    <ULink v-for="item in navigation" :key="item.path" :to="item.path" class="text-sm">
      {{ item.title }}
    </ULink>
  </UContainer>
</template>

LanguageSwitcher

The language switcher shown when internationalization is enabled with several locales.

LanguageSwitcher
app/components/LanguageSwitcher.vue
<script setup lang="ts">
const { locale, locales, switchLocalePath } = useMovkI18n()
</script>

<template>
  <div class="flex gap-2 text-sm">
    <NuxtLink
      v-for="item in locales"
      :key="item.code"
      :to="switchLocalePath(item.code)"
      :class="item.code === locale ? 'text-highlighted' : 'text-muted'"
    >
      {{ item.name }}
    </NuxtLink>
  </div>
</template>

ThemePicker

The visitor theme picker for primary color, neutral color, radius, icon set and color mode, with config export, see Theme & Fonts. Override it with an empty component if you do not need it:

ThemePicker
app/components/ThemePicker.vue
<template>
  <span class="hidden" />
</template>

Docs pages

The "Copy page" button and dropdown at the right end of the metadata row: copy the Markdown link, view as Markdown, open in ChatGPT or Claude, and, when MCP is enabled, copy the MCP URL or add it to VS Code and Cursor.

PageHeaderLinks
app/components/PageHeaderLinks.vue
<script setup lang="ts">
const route = useRoute()
</script>

<template>
  <UButton
    :to="`/raw${route.path}.md`"
    target="_blank"
    label="Markdown"
    icon="i-lucide-file-text"
    size="xs"
    variant="link"
    color="neutral"
  />
</template>

DocsAsideLeftTop

The top of the left sidebar. By default it is the navigation filter, rendered only when aside.filter.enabled is on and the current section reaches the threshold, see Navigation & Categories.

DocsAsideLeftTop
app/components/DocsAsideLeftTop.vue
<script setup lang="ts">
const searchTerm = inject<Ref<string>>('docsFilterSearch', ref(''))
</script>

<template>
  <UInput v-model="searchTerm" icon="i-lucide-search" placeholder="Filter..." class="w-full" />
</template>

docsFilterSearch is the filter term provided by the docs layout; DocsAsideLeftBody filters the navigation with it.

DocsAsideLeftBody

The body of the left sidebar: docs navigation grouped by section, with an indicator next to the current item that slides on navigation.

DocsAsideLeftBody
app/components/DocsAsideLeftBody.vue
<script setup lang="ts">
const navigation = useDocsNavigation()
const { navigationByCategory } = useNavigation(navigation)
</script>

<template>
  <div v-for="group in navigationByCategory" :key="group.path" class="mb-6">
    <p class="mb-2 text-sm font-semibold">
      {{ group.title }}
    </p>
    <UContentNavigation :navigation="group.children" :collapsible="false" />
  </div>
</template>

DocsAsideRightBottom

The area below the table of contents. By default it shows the "Explain with AI" button when AI Chat is enabled.

DocsAsideRightBottom
app/components/DocsAsideRightBottom.vue
<template>
  <UPageLinks
    title="Community"
    :links="[{ label: 'Discussions', icon: 'i-lucide-messages-square', to: 'https://github.com/my/repo/discussions', target: '_blank' }]"
  />
</template>

The footer container, mounting FooterLeft and FooterRight on either side.

Footer
app/components/Footer.vue
<template>
  <UFooter>
    <template #left>
      <FooterLeft />
    </template>

    <template #right>
      <FooterRight />
    </template>
  </UFooter>
</template>

FooterLeft

Renders footer.credits as MDC by default.

FooterLeft
app/components/FooterLeft.vue
<template>
  <p class="text-sm text-muted">
    © 2026 My Team · Released under the MIT License
  </p>
</template>

FooterRight

Renders the icon buttons from footer.socials by default.

FooterRight
app/components/FooterRight.vue
<script setup lang="ts">
const { footer } = useAppConfig()
</script>

<template>
  <div class="flex gap-1">
    <UButton
      v-for="link in footer.socials"
      :key="link.to"
      v-bind="link"
      color="neutral"
      variant="ghost"
    />
  </div>
</template>
Copyright © 2024 - 2026