Skip to main content

​
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: 
<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: 
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.
<script setup>
import { useData, watchEffect } from 'vitepress'

const { isDark } = useData()

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

Build docs developers (and LLMs) love

Get started for freeTalk to us