useHeader

Provides the desktop and mobile header navigation links. Declare them in header.nav and header.mobileNav in app.config; override the composable with a same-named file in your project only when links must be generated from runtime state.

useHeader() resolves header.nav / header.mobileNav from app.config into links ready to render for the current locale. HeaderCenter renders desktopLinks and the mobile drawer HeaderBody renders mobileLinks.

Most sites never touch this function. Declare the links in app.config, see Navigation and Categories:

app/app.config.ts
export default defineAppConfig({
  header: {
    nav: [
      { label: { 'zh-CN': '文档', 'en': 'Docs' }, to: '/docs/getting-started', activeMatch: '/docs' },
      { label: 'GitHub', to: 'https://github.com/owner/repo' }
    ]
  }
})

Signature

function useHeader(): {
  desktopLinks: ComputedRef<NavLink[]>
  mobileLinks: ComputedRef<NavLink[]>
}

interface NavLink {
  label: string
  to: string
  icon?: string
  target?: '_blank' | '_self'
  active: boolean
}

Return Value

NameTypeDescription
desktopLinksComputedRef<NavLink[]>Desktop links resolved from header.nav
mobileLinksComputedRef<NavLink[]>Mobile links resolved from header.mobileNav; falls back to header.nav when mobileNav is empty

Resolution rules:

  • When label is a per-locale object, the current locale is used first, then the default locale, then the first value.
  • Internal links get the locale prefix through localePath; external links are kept as-is and default to target: '_blank'.
  • An explicit active wins; otherwise an internal link is active when the current path starts with activeMatch (defaults to to). External links are never active.

Overriding

When navigation depends on login state, remote data and so on, create a same-named file in your project. Project composables take precedence over the layer's auto-import:

app/composables/useHeader.ts
export function useHeader() {
  const route = useRoute()
  const { localePath } = useMovkI18n()

  const desktopLinks = computed(() => [
    { label: 'Docs', to: localePath('/docs/getting-started'), active: route.path.startsWith(localePath('/docs')) },
    { label: 'Blog', to: 'https://example.com/blog', target: '_blank' as const, active: false }
  ])

  return {
    desktopLinks,
    mobileLinks: desktopLinks
  }
}

An override must return both desktopLinks and mobileLinks, with items shaped like NavLink. Once overridden, header.nav / header.mobileNav no longer apply.

Changelog

No recent changes
Copyright © 2024 - 2026