Reference
Composables
Composables API reference
Return Value
All composables return:
const {
data, // ComputedRef<T | undefined> - The fetched data
pending, // Ref<boolean> - Loading state
error, // Ref<Error | undefined> - Error if failed
status, // Ref<'idle' | 'pending' | 'success' | 'error'>
refresh, // () => Promise<void> - Refetch data
execute, // () => Promise<void> - Execute query
clear, // () => void - Clear data and error
transformError, // Ref<Error | undefined> - Error during data transformation
retryCount, // Ref<number> - Number of retries attempted
isRetrying, // Ref<boolean> - Whether currently retrying
} = usePosts()
Options
usePosts(variables?, options?)
| Option | Type | Default | Description |
|---|---|---|---|
lazy | boolean | false | Don't block navigation |
server | boolean | true | Fetch during SSR |
immediate | boolean | true | Fetch immediately |
watch | any[] | — | Refetch when values change |
transform | (data) => T | — | Transform response |
clientCache | boolean | true | Enable client-side caching |
getCachedData | function | — | Custom cache control function |
retry | boolean | number | false | Enable retry with optional count |
retryDelay | number | 1000 | Delay between retries (ms) |
timeout | number | 0 | Request timeout (ms), 0 = disabled |
Examples
// Client-only
usePosts(undefined, { server: false })
// Manual execution
const { execute } = usePosts(undefined, { immediate: false })
await execute()
// Watch reactive value
const category = ref('news')
usePosts({ categoryName: category }, { watch: [category] })
// Transform
usePosts(undefined, {
transform: (posts) => posts?.map(p => p.title)
})
// Disable client caching for real-time data
usePosts(undefined, { clientCache: false })
// Enable retry on failure (3 attempts)
usePosts(undefined, { retry: 3 })
// Custom retry delay
usePosts(undefined, { retry: 3, retryDelay: 2000 })
// Enable timeout (10 seconds)
usePosts(undefined, { timeout: 10000 })
Default Composables
Posts
| Composable | Variables |
|---|---|
usePosts() | { first?: number } |
usePostByUri() | { uri: string } |
usePostById() | { id: string } |
usePostsByCategoryName() | { categoryName: string } |
usePostsByCategoryId() | { categoryId: number } |
Pages
| Composable | Variables |
|---|---|
usePages() | { first?: number } |
usePageByUri() | { uri: string } |
usePageById() | { id: string } |
Other
| Composable | Variables |
|---|---|
useMenu() | { name: string } |
useNodeByUri() | { uri: string } |
useGeneralSettings() | — |
useViewer() | — |
useRevisions() | { id: string } |
Navigation
| Composable | Description |
|---|---|
usePrevNextPost(slug) | Get previous/next posts for navigation |
const { prev, next } = await usePrevNextPost('my-post-slug')
// prev/next contain: { slug, uri, title }
Lazy Mode
Use the lazy: true option for non-blocking navigation:
// Navigation happens immediately, data loads in background
usePosts({}, { lazy: true })
usePostByUri({ uri }, { lazy: true })
usePages({}, { lazy: true })
Custom Composables
Create .gql files in extend/queries/ to generate custom composables:
extend/queries/FeaturedPosts.gql
query FeaturedPosts($limit: Int = 5) {
posts(first: $limit, where: { tag: "featured" }) {
nodes { ...Post }
}
}
Generates useFeaturedPosts({ limit }) which you can use with the { lazy: true } option when needed.
Utilities
getRelativeImagePath
Converts WordPress absolute image URLs to relative paths for use with NuxtImage:
const imageUrl = 'https://wordpress.example.com/wp-content/uploads/2024/01/photo.jpg'
const relativePath = getRelativeImagePath(imageUrl)
// Returns: '/wp-content/uploads/2024/01/photo.jpg'
Usage with NuxtImage:
<NuxtImg :src="getRelativeImagePath(post.featuredImage?.node?.sourceUrl)" />
TypeScript
Types are auto-generated from your GraphQL schema:
import type { PostFragment } from '#graphql-operations'
const { data: posts } = usePosts()
// posts: ComputedRef<PostFragment[] | undefined>