Creating global components and referencing them in Storyblok

In Storyblok, you can define your content structure in smaller pieces, so-called Components, if a purely flat structure, which is also possible, is not enough. Think of something more complex than a blog article that already works with only one markdown field. Let's think about a landing page with the same header and footer on every page. Sometimes, you might also have things like a newsletter or form sections that you want for some pages, right? Let's see how you can achieve both with Storyblok. Make sure to have an account and create your space. Assuming you already have done that, we will jump into setting up the structure.

Section titled What we're about to do What we're about to do

The use-case for this would be content repeated on multiple sites, and you want to keep the content the same throughout. Depending on whether you have them on all pages or only on specific ones, you can either load them directly in your implementation or load them as part of your reference - your choice.

1. Creating a folder that contains all our global entries
2. Define a content type for our global components
3. Create a field in that content type that holds our component
4. Create a reference component so we can link them
5. Check out our resolve_relations API feature to link to the global components

Section titled Follow along guide Follow along guide

We will set up a folder in Storyblok. During the creation of that new folder, you're able to define a content-type. This content type will be the holder for our new global components, so let's go with global as the name for the entry that's going to hold our components. We will also enable the option that nobody can change the content type in the global folder, so we only have entries of that type here. In the same step, we will also make sure to use the default content type option so global is already selected.

Once you've created that folder, we can now create our first entry in there. We must ensure use the content type global while we create that new entry. Since we've disabled the possibility of changing the content type for the folder, this should already be on global by default. Enter any name you want for the entry itself, but make sure this name will explain the content of the global component in the entry to your editors. We are going for the "Newsletter Section" as this is the one we want to have on multiple pages and reference to it.

The next step will be to set up the actual field in the entry that holds our component, for this we will click on "Define Schema" and add a new field called global of the type blok. Pressing "Save" will allow you to add new components anytime. If you want to limit that, you can go back to "Define Schema" and use the advanced option to limit the number and type of components (and even component groups) added as global components.

Once you've done that, we will be able to add the actual component that you want to be able to reference from everywhere. We will go for our already existing component, the newsletter-section. Feel free to use one of yours or create a new one. If you're using a new space, you will also find a teaser component you can use as an example.

Section titled Creating the reference component Creating the reference component

Now that we have the structure defined for our global components, we will reference them. To reference such an entry, all we have to do is to define a field of the type single-option or multi-options in existing components or create a new component which only use-case is to reference to those.

First, we will navigate the Block Library menu and hit "New" in the top right corner. You will be prompted with an input field to name the component, we will use global_reference. After confirming the name, we will add a new field called reference and hit "Add."

You will now be able to choose the field type, the one we want in this example is single-option. However, if you want to reference multiple global components simultaneously, you can use the multi-option similarly. Once you've selected single-option, you can choose "Stories" as your source. Below that drop-down of source types, we will also enter global/ for "Path to folder of stories." Once done, we will hit the "Save schema" button on the top right corner.

You can now use that global reference in every Bloks field as you would with your normal component. Now, however, all we will do there is select the entry that contains the component we want to display at this place, in our example, the newsletter section.

Once pressing Save, you will already be able to consume the reference:

This will be your response.

Section titled Resolving the relationship with the API Resolving the relationship with the API

You will notice that we're only storing the UUID of referenced Story and you would now already be able to load that specific entry by its UUID. However, what we want to do here is to have that content included in the initial response and not have to load it with a second request. Since we're now using a generic reference component for all our global entries, all we have to do is use the resolve_relations as an additional query parameter:

Our response will result in us having the UUID of the global_reference the component being resolved to the actual whole Story entry in a rels array.

Section titled Wrap up Wrap up

You can now create multiple global components and reuse them in other places like that. Using that method for components you have on every site is something we would not recommend – we would recommend loading them once, storing them, and reusing them from there. A good example of that would be Header and Footer which can be on every page, and you would be better off sending one additional request once rather them having the whole content included on every request.