Data Fetching Methods

KQL for content queries that follow relationships and filter; the REST API for plain requests, file handling and endpoints of your own.

TIP

In most cases, KQL queries with useKql and $kql are preferred for their flexibility and type safety.

Methods Comparison

Access your Kirby CMS data using either KQL or direct API access:

Method	Composables	Description
KQL	useKql, $kql	Kirby Query Language, for content queries that follow relationships and filter.
Direct Kirby API Access	useKirbyData, $kirby	Direct access to Kirby's REST API for custom endpoints.

Composables Comparison

In your Vue components, you can choose between reactive data fetching with useKirbyData / useKql or programmatic one-time actions with $kirby / $kql.

Feature	useKirbyData / useKql	$kirby / $kql
Use case	Components, reactive data	One-time actions
Return type	AsyncData interface	Direct Promise
Error handling	Reactive error property	Try/catch with FetchError

Method 1: KQL (Kirby Query Language)

Use useKql and $kql as your daily driver for fetching content from Kirby. KQL is designed to handle complex queries and relationships efficiently.

Commonly, use useKql in your Vue components to fetch and reactively update data. For example, fetching a page's title and text:

<script setup lang="ts">
const { data } = await useKql({
  query: 'page("home")',
  select: {
    title: true,
    text: 'page.text.kirbytext',
  }
})
</script>

<template>
  <div>
    <h1>{{ data?.result?.title }}</h1>
    <div v-html="data?.result?.text" />
  </div>
</template>

Method 2: Direct Kirby API Access

Use useKirbyData and $kirby to access Kirby's REST API directly. This method is ideal when you need to fetch simple data, download files, or interact with custom endpoints.

A common example is a Nuxt plugin that fetches site-wide settings once and stores them in a global state for easy access across your application:

import type { FetchError } from 'ofetch'

export default defineNuxtPlugin(async (nuxtApp) => {
  const site = useState('site', () => ({}))

  // Fetch site data once from a custom API endpoint
  if (import.meta.server) {
    try {
      const data = await $kirby('api/site')
      site.value = data?.result || {}
    }
    catch (e) {
      console.error('Failed to fetch site data:', (e as FetchError).message)
    }
  }
})

Batching KQL Queries

Several queries can travel in one request, so a page that needs site, navigation and a listing costs one round trip rather than three. Nuxt Kirby supports batching multiple queries into a single request using the useKql composable.

To batch multiple queries, pass an object to the select property. Each key represents a separate query:

// Optional: DRY up your queries by defining them in a separate file
import { articlesQuery, navigationQuery, siteQuery } from '~/queries'

// Batch multiple KQL queries in a single request
const { data } = await useKql({
  query: 'site',
  select: {
    site: siteQuery,
    articles: articlesQuery,
    navigation: navigationQuery
  }
})

// Access the results of each query
const site = computed(() => data.value?.result.site)
const articles = computed(() => data.value?.result.articles)
const navigation = computed(() => data.value?.result.navigation)