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

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

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

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

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.

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

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

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

Further resources

• Creating global components and referencing them in Storyblok Opens in new tab
• Retrieving Stories with Resolved Relations Opens in new tab