queryCollectionItemSurroundings

Usage

Use the auto-imported queryCollectionItemSurroundings to find the previous and next items relative to a specific content item in a collection. This is particularly useful for creating navigation between related content pages.

The function returns a chainable promise that allows you to add additional query conditions:

<script setup lang="ts">
const { data } = await useAsyncData('surround', () => {
  return queryCollectionItemSurroundings('docs', '/foo')
    .where('published', '=', true)
    .order('date', 'DESC')
})
</script>

Type

function queryCollectionItemSurroundings<T extends keyof PageCollections>(
  collection: T,
  path: string,
  opts?: SurroundOptions<keyof PageCollections[T]>
): ChainablePromise<T, ContentNavigationItem[]>

interface ChainablePromise<T extends keyof PageCollections, R> extends Promise<R> {
  where(field: keyof PageCollections[T] | string, operator: SQLOperator, value?: unknown): ChainablePromise<T, R>
  andWhere(groupFactory: QueryGroupFunction<PageCollections[T]>): ChainablePromise<T, R>
  orWhere(groupFactory: QueryGroupFunction<PageCollections[T]>): ChainablePromise<T, R>
  order(field: keyof PageCollections[T], direction: 'ASC' | 'DESC'): ChainablePromise<T, R>
}

API

queryCollectionItemSurroundings(collection: CollectionName, path: string, opts?: SurroundOptions)

Find the surrounding items (previous and next) for a specific content item in a collection.

• Parameters:
  • collection: The key of the defined collection in content.config.ts.
  • path: The path of the current content item.
  • opts: (Optional) An object with the following properties:
    • before: (Optional) The number of items to fetch before the current item. Default is 1.
    • after: (Optional) The number of items to fetch after the current item. Default is 1.
    • fields: (Optional) An array of additional fields to include in the surrounding items.
• Returns: A chainable promise that resolves to an array containing the surrounding items. The promise includes methods for adding query conditions:
  • where(field, operator, value): Add a WHERE condition
  • andWhere(groupFactory): Add a grouped AND condition
  • orWhere(groupFactory): Add a grouped OR condition
  • order(field, direction): Add an ORDER BY clause

The final result will be an array with the following structure:

• [previousItem, nextItem] if using default options
• [...previousItems, ...nextItems] if using custom before and after values

Each item in the array is of type ContentNavigationItem or null if there is no item in that position.

Examples

Basic usage without additional query conditions:

<script setup lang="ts">
const { data } = await useAsyncData('surround', () => {
  return queryCollectionItemSurroundings('docs', '/foo')
})
</script>

<template>
  <div class="flex justify-between">
    <NuxtLink v-if="data?.[0]" :to="data[0].path">
      ← {{ data[0].title }}
    </NuxtLink>
    <NuxtLink v-if="data?.[1]" :to="data[1].path">
      {{ data[1].title }} →
    </NuxtLink>
  </div>
</template>

Example with additional query conditions:

<script setup lang="ts">
const { data } = await useAsyncData('surround', () => {
  return queryCollectionItemSurroundings('docs', '/foo', {
    before: 1,
    after: 1,
    fields: ['badge', 'description']
  })
    .where('_draft', '=', false)
    .where('_partial', '=', false)
    .order('date', 'DESC')
})
</script>

Server Usage

Nuxt Content provides a similar utility to query collections on the server side. The only difference is that you need to pass event as the first argument to the queryCollectionItemSurroundings function.

export default eventHandler(async (event) => {
  const surroundings = await queryCollectionItemSurroundings(event, 'docs', '/foo')
  return surroundings
})

{
  "extends": "../.nuxt/tsconfig.server.json"
}