Custom Queries

WPNuxt ships with default composables for common WordPress content — posts, pages, menus, and settings. Custom queries let you go beyond the defaults: fetch ACF fields, custom post types, SEO metadata, WooCommerce products, or lighter data shapes that only include the fields you need.

When to Create Custom Queries

Complete Workflow

1. Check Your Schema

Before writing a query, verify that the fields you need exist in your WordPress GraphQL schema. Visit {your-wordpress-url}/graphql to open the GraphQL IDE and explore available types and fields.

2. Create the Query File

Add a .gql file to extend/queries/:

query FeaturedPosts($limit: Int = 5) {
  posts(first: $limit, where: { tag: "featured" }) {
    nodes {
      ...Post
    }
  }
}

3. Regenerate Types

Run prepare to trigger the composable generation pipeline:

pnpm nuxt prepare

4. Use the Composable

The composable is auto-imported and fully typed:

<script setup lang="ts">
const { data: featured } = await useFeaturedPosts({ limit: 3 })
</script>

<template>
  <article v-for="post in featured" :key="post.id">
    <h2>{{ post.title }}</h2>
  </article>
</template>

5. Verify Types

Hover over featured in your editor — you should see the correct TypeScript types based on the fields in your query and fragment.

Using Fragments

Fragments let you define reusable sets of fields. This is useful when multiple queries need the same fields, or when you want to extend WPNuxt's built-in fragments with additional data.

Place fragment files in extend/queries/fragments/ with a .fragment.gql extension:

fragment PostWithAuthor on Post {
  ...Post
  author {
    node {
      name
      avatar {
        url
      }
    }
  }
}

Then use the fragment in a query:

query AuthorPosts($authorId: Int!) {
  posts(where: { author: $authorId }) {
    nodes {
      ...PostWithAuthor
    }
  }
}

Overriding Default Queries

To modify what a default composable returns, create a file with the same name as the default query:

query Posts($first: Int = 10) {
  posts(first: $first) {
    nodes {
      ...Post
      customField
      seo {
        title
        metaDesc
      }
    }
  }
}

Your version replaces the default. The composable name stays the same — usePosts() will now return your custom fields.

How Query Merging Works

At build time, WPNuxt merges queries from two sources:

1. Default queries from @wpnuxt/core (src/runtime/queries/)
2. Your queries from extend/queries/ (configurable via wpNuxt.queries.extendFolder)

Both are copied to a .queries/ folder. If a file exists in both locations, your version wins. The merged folder is then parsed to generate composables. This is why you can override any default query by matching its filename.

Folder Structure

extend/
└── queries/
    ├── FeaturedPosts.gql           ← new custom query
    ├── Posts.gql                   ← overrides default Posts query
    ├── AuthorPosts.gql             ← new custom query
    └── fragments/
        └── PostWithAuthor.fragment.gql

Troubleshooting

Related Pages

• How WPNuxt Works — Understand the composable generation pipeline
• Fetching Data — Composable options (lazy loading, watching, refreshing)
• Configuration — Configure the queries folder path