Composables

Vue composables for accessing route, data, and router in VitePress

Composables

VitePress provides several Vue composables that give you access to app data, routing, and theme configuration.

Core Composables

useData

Access page-level and site-level data.

import { useData } from 'vitepress'

const { site, page, frontmatter, theme, isDark, lang, title } = useData()

Returns: VitePressData<T>

site · Ref<SiteData<T>>

Site-level metadata and configuration

theme · Ref<T>

The themeConfig from .vitepress/config.js

page · Ref<PageData>

Current page metadata including frontmatter, headers, and file paths

frontmatter · Ref<Record<string, any>>

Frontmatter data for the current page

params · Ref<Record<string, any>>

Dynamic route parameters (for data loading)

title · Ref<string>

Current page title (computed from frontmatter or first h1)

description · Ref<string>

Current page description

lang · Ref<string>

Current language code

dir · Ref<string>

Text direction (ltr or rtl)

localeIndex · Ref<string>

Current locale index (e.g., 'root', 'zh', 'en')

isDark · Ref<boolean>

Whether dark mode is currently active

hash · Ref<string>

Current location hash (e.g., #introduction)

Example Usage:

Theme Component

<script setup>
import { useData } from 'vitepress'

const { theme, isDark } = useData()
</script>

<template>
  <nav :class="{ dark: isDark }">
    <a :href="theme.socialLinks.github">GitHub</a>
  </nav>
</template>

---

useRoute

Access the current route information.

import { useRoute } from 'vitepress'

const route = useRoute()

Returns: Route (reactive object)

path · string

Current URL path (e.g., /guide/introduction.html)

hash · string

Current URL hash (e.g., #heading-anchor)

query · string

Current URL query string (e.g., ?tab=1&view=grid)

data · PageData

Current page data object

component · Component | null

Current page component

Example Usage:

<script setup>
import { useRoute, watch } from 'vitepress'

const route = useRoute()

// Track page views on route change
watch(() => route.path, (newPath) => {
  analytics.trackPageView(newPath)
})
</script>

<template>
  <div>Current page: {{ route.data.title }}</div>
</template>

---

useRouter

Access the router instance for programmatic navigation.

import { useRouter } from 'vitepress'

const router = useRouter()

Returns: Router

route · Route

Current route object (same as useRoute())

go · (to: string, options?) => Promise<void>

Navigate to a new URL

Navigation Options:

to · string · required

The URL to navigate to

options.smoothScroll · boolean · default: "false"

Whether to smoothly scroll to the target position

options.replace · boolean · default: "false"

Whether to replace the current history entry instead of pushing a new one

Router Hooks:

onBeforeRouteChange · (to: string) => Awaitable<void | boolean>

Called before the route changes. Return false to cancel navigation.

onBeforePageLoad · (to: string) => Awaitable<void | boolean>

Called before the page component loads. Return false to cancel.

onAfterPageLoad · (to: string) => Awaitable<void>

Called after the page component loads but before update.

onAfterRouteChange · (to: string) => Awaitable<void>

Called after the route changes.

Example Usage:

Programmatic Navigation

import { useRouter } from 'vitepress'

const router = useRouter()

// Navigate to a page
router.go('/quickstart')

// Navigate with smooth scroll
router.go('/api/config#appearance', { smoothScroll: true })

// Replace current history entry
router.go('/new-page', { replace: true })

---

Type Definitions

VitePressData

interface VitePressData<T = any> {
  site: Ref<SiteData<T>>
  theme: Ref<T>
  page: Ref<PageData>
  frontmatter: Ref<PageData['frontmatter']>
  params: Ref<PageData['params']>
  title: Ref<string>
  description: Ref<string>
  lang: Ref<string>
  dir: Ref<string>
  localeIndex: Ref<string>
  isDark: Ref<boolean>
  hash: Ref<string>
}

Route

interface Route {
  path: string
  hash: string
  query: string
  data: PageData
  component: Component | null
}

Router

interface Router {
  route: Route
  go: (to: string, options?: {
    smoothScroll?: boolean
    replace?: boolean
  }) => Promise<void>
  onBeforeRouteChange?: (to: string) => Awaitable<void | boolean>
  onBeforePageLoad?: (to: string) => Awaitable<void | boolean>
  onAfterPageLoad?: (to: string) => Awaitable<void>
  onAfterRouteChange?: (to: string) => Awaitable<void>
}

PageData

interface PageData {
  relativePath: string
  filePath: string
  title: string
  titleTemplate?: string | boolean
  description: string
  headers: Header[]
  frontmatter: Record<string, any>
  params?: Record<string, any>
  isNotFound?: boolean
  lastUpdated?: number
}

SiteData

interface SiteData<ThemeConfig = any> {
  base: string
  cleanUrls?: boolean
  lang: string
  dir: string
  title: string
  titleTemplate?: string | boolean
  description: string
  head: HeadConfig[]
  appearance: boolean | 'dark' | 'force-dark' | 'force-auto'
  themeConfig: ThemeConfig
  scrollOffset: number | string | string[]
  locales: LocaleConfig<ThemeConfig>
  localeIndex?: string
  contentProps?: Record<string, any>
}

---

Usage Tips

Reactive Updates: All data returned from composables is reactive. Use Vue’s watch or watchEffect to respond to changes.

SSR Compatibility: When using these composables, ensure your code handles SSR correctly. Use onMounted for browser-only logic.

Reactive Example

<script setup>
import { useData, watchEffect } from 'vitepress'

const { isDark } = useData()

watchEffect(() => {
  // Runs whenever isDark changes
  document.body.classList.toggle('dark', isDark.value)
})
</script>