---
title: References
description: Discover Storyblok's documentation with comprehensive developer guides, user manuals, API references, and examples to help you get the most out of the headless CMS platform.
url: https://storyblok.com/docs/concepts/references
---

# References

A reference is a link to another story, within a story. In the default API response, references will contain only the UUID of the linked story, but data from the linked story can be populated with `resolve_relations` API parameter.

References to stories can be implemented with the References, Single-Option, or Multi-Options [fields](/docs/concepts/fields). They are useful when certain information should ideally be managed from a single content entry and be (partially) included in other content entries.

Typical scenarios are:

-   Referencing an author profile in multiple news articles
-   Referencing a call to action in multiple landing pages
-   Referencing a selection of featured news articles on an index page

## Example content structure

Consider the following example content structure:

-   `page`: Content type
    -   `body`: Blocks field
-   `article`: Content type
    -   `headline`: Text field
    -   `description`: Textarea field
    -   `image`: Asset field
-   `featured_articles`: Nestable block
    -   `headline`: Text field
    -   `articles`: References field
-   An `articles` folder with two example stories of the type `article`
-   A `featured_articles` block in the `body` field of the `home` story, with the two example articles selected in the `articles` field

A visual representation of the example content structure.

```html
home (story)
└── body (blocks field)
    └── featured_articles (nestable block)
        ├── headline (text field)
        └── articles (references)
            ├── article_one (reference)
            └── article_two (reference)

articles (folder)
├── article_one (story)
│   ├── description (textarea field)
│   └── image (asset field)
└── article_two (story)
    ├── description (textarea field)
    └── image (asset field)
```

## Resolve relations in API requests

Fetching the `home` story and investigating the API response reveals only the UUIDs of the stories referenced in the `articles` field are included:code

An excerpt of the API response returned when requesting a single story

```json
{
  "_uid": "21507982-8728-4954-b4ad-f5066aed3c57",
  "articles": [
    "dc2d7d17-ba41-42d5-8bb4-ecae4b1f1b11",
    "d205aaf8-abf2-408f-a40e-3449c4c32d38",
    "62917fbc-f89d-4478-90a2-950d728b909b"
  ],
  "headline": "This's Week's Featured Articles",
  "component": "featured_articles"
}
```

Access articles’ content by employing the `resolve_relations` parameter. This parameter requires the technical name of the immediate parent component of the field, followed by a dot and the field name. Multiple references can be retrieved simultaneously by providing a comma-separated list. The following API request resolves the `articles` field:

An example API request using the resolve\_relations parameter.

```javascript
const { data } = await storyblokApi.get('cdn/stories/home', {
  version: 'draft',
  resolve_relations: 'featured_articles.articles',
})
```

The complete story objects of the articles are included in the `rels` array of the response for this request and can subsequently be used to display the desired content.hint

> [!TIP]
> When using `storyblok-js-client` or any of Storyblok’s JavaScript-based frontend SDKs, the `rels` array is automatically inserted at the component level for your convenience.

Learn more in the [Content Delivery API documentation](https://www.storyblok.com/docs/api/content-delivery/v2).

## Configure the Storyblok Bridge

Whenever content is changed in the Visual Editor, an updated story reflecting these changes is sent to the preview environment using `postMessage()`. Use the Storyblok Bridge’s `resolveRelations` parameter to resolve references to stories. Define an array of relations to be resolved to streamline the process.

Resolve relations for the API request and the Storyblok Bridge

```javascript
import { storyblokInit, apiPlugin, useStoryblokBridge } from '@storyblok/js'

const { storyblokApi } = storyblokInit({
  accessToken: 'your-storyblok-access-token',
  use: [apiPlugin],
  bridge: true,
})

try {
  const resolveRelations = ['featured_articles.articles']

  const { data } = await storyblokApi.get('cdn/stories/home', {
    version: 'draft',
    resolve_relations: resolveRelations,
  })
  const { story } = data

  useStoryblokBridge(story.id, (story) => updateStory(story), { resolveRelations })
} catch (error) {
  console.log(error)
}
```

Learn more in the [Bridge reference](/docs/libraries/js/preview-bridge).

## Fetch references manually

References can be fetched manually with subsequent API requests. While less convenient, it offers the benefit of additional control over what gets fetched. Use the `excluding_fields` parameter to specify which fields should be part of the API response. Consider the following example in which the `description` and `image` fields are excluded:

Use the excluding\_fields parameter in a subsequent API request to retrieve referenced stories

```javascript
import { storyblokInit, apiPlugin, useStoryblokBridge } from '@storyblok/js'

const { storyblokApi } = storyblokInit({
  accessToken: 'your-storyblok-access-token',
  use: [apiPlugin],
})

try {
  const resolveRelations = ['featured_articles.articles']

  const { data } = await storyblokApi.get('cdn/stories/home', {
    version: 'draft',
  })
  const { story } = data

  const { data } = await storyblokApi.get('cdn/stories', {
      version: 'draft',
      by_uuids: story.content.body[0].articles.toString(),
      excluding_fields: 'description,image',
    })

  console.log(data.stories)
} catch (error) {
  console.log(error)
}
```

> [!NOTE]
> When attempting to resolve more than 50 references, instead of resolving to the `rels` array, the API returns a `rel_uuids` array containing the UUIDs of stories to be resolved. This can be used for a subsequent API request. Storyblok’s JavaScript-based frontend SDKs automatically resolve more than 50 relations under the hood.

## Further resources

[Creating global components and referencing them in Storyblok](https://www.storyblok.com/tp/global-components-references)

[Retrieving Stories with Resolved Relations](https://www.storyblok.com/docs/api/content-delivery/v2/stories/examples/retrieving-stories-with-resolved-relations)

## Pagination

-   [Previous: Internationalization](/docs/concepts/internationalization)
-   [Next: Roles](/docs/concepts/roles)