---
title: "queryCollectionItemSurroundings"
description: "The queryCollectionItemSurroundings composable looks for sibling contents of an specific path."
canonical_url: "https://content.nuxt.com/docs/utils/query-collection-item-surroundings"
---
# queryCollectionItemSurroundings

> The queryCollectionItemSurroundings composable looks for sibling contents of an specific path.

## 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:

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

<tip>

The `queryCollectionItemSurroundings` utility is available in both Vue and Nitro. Checkout [Server Usage](#server-usage) for more details on how to use it on the server side.

</tip>

## Type

```ts
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:

```vue [pages/[...slug].vue]
<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:

```vue [pages/[...slug].vue]
<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.

```ts [server/api/surroundings.ts]
export default eventHandler(async (event) => {
  const surroundings = await queryCollectionItemSurroundings(event, 'docs', '/foo')
  return surroundings
})
```

<note>

Make sure to create `server/tsconfig.json` file with the following content to avoid type error.

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

</note>


## Sitemap

See the full [sitemap](https://content.nuxt.com/sitemap.md) for all pages.