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. 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.

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)

Resolving 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

{
  "_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.

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.

For further information, please refer to the Content Delivery API documentation.

Configuring 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(). The Storyblok Bridge’s resolveRelations parameter can be utilized to resolve references to stories. The process can be streamlined by defining an array of relations to be resolved.

Resolving relations for the API request and the Storyblok Bridge

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)
}

For further information, please refer to the Bridge reference.

Fetching 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:cod

Using the exluding_fields parameter in a subsequent API request to retrieve referenced stories

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 will return a rel_uuids array containing the UUIDs of stories to be resolved. This can be utilized for a subsequent API request. When using storyblok-js-client or any of Storyblok’s JavaScript-based frontend SDKs, resolving more than 50 relations is automatically handled under the hood for your convenience.

Further resources

Creating global components and referencing them in Storyblok

Retrieving Stories with Resolved Relations