API Reference
Complete API reference for composables and utilities.
Composables
useAsyncData
Fetch data asynchronously with automatic caching and SSR support.
const { data, pending, error, refresh } = await useAsyncData(
'unique-key',
() => queryCollection('posts').all()
)
Parameters:
key(string): Unique identifier for cachinghandler(function): Async function that returns data
Returns:
data: Reactive data referencepending: Loading stateerror: Error staterefresh: Function to refetch data
useSeoMeta
Set SEO meta tags for the current page.
useSeoMeta({
title: 'Page Title',
ogTitle: 'Page Title',
description: 'Page description',
ogDescription: 'Page description',
ogImage: 'https://example.com/image.jpg'
})
useRoute
Access the current route information.
const route = useRoute()
console.log(route.path) // Current path
console.log(route.params) // Route parameters
console.log(route.query) // Query parameters
useRouter
Navigate programmatically.
const router = useRouter()
// Navigate to a route
router.push('/api-docs')
// Navigate with parameters
router.push({
path: '/api-docs',
query: { section: 'api' }
})
// Go back
router.back()
useColorMode
Manage color mode (light/dark theme).
const colorMode = useColorMode()
// Get current mode
console.log(colorMode.value) // 'light' or 'dark'
// Set mode
colorMode.preference = 'dark'
// Toggle mode
const toggleDark = () => {
colorMode.preference = colorMode.value === 'dark' ? 'light' : 'dark'
}
Content Queries
queryCollection
Query content collections with filtering and sorting.
// Get all items
const posts = await queryCollection('posts').all()
// Get first item
const page = await queryCollection('pages').first()
// Filter by path
const doc = await queryCollection('apiDocs')
.path('/api-docs/getting-started')
.first()
// Order results
const versions = await queryCollection('versions')
.order('date', 'DESC')
.all()
queryCollectionItemSurroundings
Get previous and next items in a collection.
const surround = await queryCollectionItemSurroundings(
'apiDocs',
route.path,
{
fields: ['title', 'description']
}
)
Utilities
definePageMeta
Define page-level metadata and configuration.
definePageMeta({
layout: 'docs',
middleware: 'auth'
})
navigateTo
Navigate to a URL.
// Navigate to internal route
await navigateTo('/api-docs')
// Navigate to external URL
await navigateTo('https://example.com', {
external: true
})
// Replace current route
await navigateTo('/api-docs', {
replace: true
})
createError
Create and throw an error.
throw createError({
statusCode: 404,
statusMessage: 'Page not found',
fatal: true
})
Type Definitions
ContentNavigationItem
interface ContentNavigationItem {
title: string
_path: string
children?: ContentNavigationItem[]
icon?: string
badge?: string
}
PageData
interface PageData {
title: string
description: string
body?: any
seo?: {
title?: string
description?: string
}
navigation?: {
icon?: string
}
}
Examples
Fetching and Displaying Data
<script setup lang="ts">
const { data: posts } = await useAsyncData('blog-posts', () =>
queryCollection('posts')
.order('date', 'DESC')
.all()
)
</script>
<template>
<div>
<UCard
v-for="post in posts"
:key="post._path"
:title="post.title"
:description="post.description"
/>
</div>
</template>
Dynamic SEO
<script setup lang="ts">
const route = useRoute()
const { data: page } = await useAsyncData(route.path, () =>
queryCollection('apiDocs').path(route.path).first()
)
useSeoMeta({
title: page.value?.title,
description: page.value?.description
})
</script>
Navigation with State
<script setup lang="ts">
const router = useRouter()
const navigateWithState = async () => {
await router.push({
path: '/api-docs',
query: {
section: 'api',
highlight: 'composables'
}
})
}
</script>