Storyblok Raises $80M Series C - Read News

What’s the True Total Price of Enterprise CMS? Find out here.

Skip to main content

Component/Schema Configuration

Field types

One field type is the smallest part in Storyblok terminology. It can be a single input field or even a custom field type (plugin). You can see the list of all field types in the following table with links to the detailed documentation of the field type.

NameShort Description
Texta basic single-line text field
Textareaa multi-line text area without formatting options
Imagea single image upload input and access to the asset manager
Date/Timea date and time picker
Booleana checkbox - true/false
Linkinternal and external links, eMail, and anchors
Filea single file upload input and access to the asset manager
Multi-Asseta multi asset upload input, including description for each and access to the asset manager
Single-Optiona dropdown of key/value pairs, Stories, Datasources, external JSONs, or Field Level Translation Languages.
Multi-Optiona multi select option of key/value pairs, Stories, Datasources, external JSONs, or Field Level Translation Languages.
References (Multi Options)a multi-select option for Stories. This field is dedicated to Stories source only to search names and URLs from Stories.
Numbera number text field without formatting
Blocksa field to allowed nesting of Bloks
Markdowna multi-line field with formatting options resulting in Markdown format
Richtexta multi-line field with formatting options that results in a JSON format
Groupallows you to group fields in a section (no input possibility)
Pluginextend the Visual Editor Content area with your own Custom Field Type

Here you can learn more about all options when configuring your content types and components in Storyblok.

Config Tab

You can find the general settings in the Config tab of your component/content type.

storyblok field configuration

Technical name

This is the technical name that will be included in the JSON content of your content entries under the attribute component. If you do not define a "Display name" the "Technical name" will be transformed to a human-readable name in the editor interface. For example: "feature_area" will be transformed to "Feature Area".

Be aware! Changing the technical name can take a few minutes to update all content items. Make sure your editors have saved their current work and exit the editor. If you use branches, only the "Preview" branch will have the new component name until you deploy the other branches.

Display name

The value of this field will be shown for editors as a component/content-type name. If this field is empty, the "Technical name" will be shown.

<div id="topic-preview"></div>

Preview field

The preview field allows you to select one of the fields you set up in the schema so that the value entered in this field will be shown when you see this block in the overview (e.g., in the body with nestable blocks). For example, if you set up a headline text field, you could set this as the preview. Storyblok automatically sets one of the fields as a preview

Preview template

With this option, you can define a template that gets rendered in the blocks field. The template language you can use here is based on Squirrelly 8.

If you still have templates based on Squirrely 7, you can see our old documentation here. Please update your old templates.

To render the preview, you use the following template.

<div>{{it.text}}</div>
<!-- ".image" is the field name -->
{{@image(it.image.filename)/}} 

<!-- old image field -->
{{@image(it.image)/}} 

All fields you have defined in your schema can be used with the following syntax: {{it.YOUR_FIELD_NAME}}. When using helpers like @if() or @image() the attributes are accessible via the it object.

Allowed HTML tags

  • Tags: div, span, strong, ul, li, p
  • Attributes: class

Styling

Preview templates can be styled using the blok ink: classes for specific text styling:

<div class="text-red">{{it.error}}</div>

Linked Stories

If you linked another story inside your schema through a single or multi-select field, you could only use the story id in the preview template, not the fields inside that linked story.

# possible
<div>{{it.linkedAuthor}}</div>

# not possible
<div>{{it.linkedAuthor.name}}</div>

Available helpers

@image

{{@image(it.image.filename)/}}

if/else

{{@if(it.your_attribute === "1")}}
Display this
{{#else}}
Display that
{{/if}}

@each

{{@each(it.somearray) => val, index}}
Display this
The current array element is {{val}}
The current index is {{index}}
{{/each}}

@foreach

{{@foreach(it.someobject) => key, val}}
This loops over each of an objects keys and values.
The value of the current child is {{val}}
The current key is {{key}}
{{/foreach}}

Preview Screenshot

This option lets you define a screenshot shown when the user inserts a new component in the blocks field. This helps the user to identify the component type better.

Block icon

Here you can set the icon that defines this block.

General configuration options

All field types except the Blocks are translatable and all field types contain general configuration options - Required, Description, Display name.

Configuration OptionsTypeDescription
TranslatableBooleanIf true, it enables translation of field in the case of the Field Level Translations.
RequiredBooleanIf true, it forbids save of the story, if the field is empty.
DescriptionStringText is shown under the field in the Storyblok Editor.
Display nameStringIt overrides the default name of the field.
RenamingStringIt allows you to change the field name.

Text

The text field should be used for short one-line long strings. The most common use case is the name of the product or author.

Configuration OptionTypeDescription
Maximum charactersNumberDefines a maximal number of allowed characters in the field.
Regex ValidationRegexYou can use the regex to validate the value of the field. Eg. to validate if the value is a valid email string.
Default ValueStringDefines the default value of the field.
Enables RTLBooleanIf true, the field value will be shown from right to left in Storyblok Editor.

hint:

Text Field can be transformed into the Textarea Field directly in the Storyblok Editor without losing the value.

Textarea

Textarea field should be used for one paragraph without the possibility of styling or creating multiple paragraphs. The most common sample is a short teaser text of a product or article.

Configuration OptionTypeDescription
Maximum charactersNumberDefines a maximal number of allowed characters in the field.
Regex ValidationRegexYou can use the regex to validate the value of the field. Eg. to validate if the value is a valid email string.
Default ValueStringDefines the default value of the field.
Enables RTLBooleanIf true, the field value will be shown from right to left in Storyblok Editor.

Image

DEPRECATED:

Image Field will be in future deprecated in the favour of the Assets Field.

The image field is used to insert or select images from the assets library. It can be used to crop your images to the preferred ratio.

Configuration OptionTypeDescription
Force CropBooleanIt toggles the preset crop options of the image. Read how to crop image section following this table for more information.
Prepend https to urlBooleanIf true, the URL of the image will be prepend with "https://".
Default assets folderSelectIt is an asset folder where the new images will be added to.
Default ValueStringDEPRECATED - have currently no effect.

How to crop the image?

You can crop the image by clicking on the image thumbnail. This action will open the image overlay, where you can select the cropped area from the original image.

If you set Force Crop to true, you are able to predefine the ratio or fixed-sized of the crop area. In this case, the content editor will be forced to crop the image in the predefined size or ratio.

hint:

Storyblok offers also Image Service with which you can adjust format, size and effects applied to your images. Read more in the Image Service documentation.

Date/Time

Configuration OptionTypeDescription
Disable time selectionBooleanIt toggles the preset crop options of the image. Read how to crop image section following this table for more information.
Default ValueStringDEPRECATED - have currently no effect.

Boolean

Boolean is one of the Basic Field Types. It indicates a checkbox, which can hold two values, either True or False.

IMPORTANT:

By default, the value of Boolean Field Type is False.

You can filter entries by boolean value. Imagine you want to allow your editors to have featured products with a boolean flag in your content schema. To filter all products to only receive the featured once you can utilize the filter_query operation to check for an exact value.

Links are another representation of your content entries, eg. Stories. With the Links format, you can resolve uuids of stories. The links object returned consists of multiple keys, where each key is the uuid of one Story. In the link object, you will have access to basic information to identify, load or already display a link to that resource.

Link Field Options
Configuration OptionTypeDescription
Restrict to content typesBooleanIf true, you can choose content types from the whitelist
Enable email fieldBooleanIf true, you will be able to add an email field
Enable asset selectionBooleanIf true, you can add asset from Asset manager or Upload new from your local machine
Enable anchor field on internal linkBooleanIf true, you will be able to set an anchor for internal links
Allow links to be open in a new tabBooleanIf true, You will be able to mark a link external. The link will have a target property of value "_blank". The default is "_self".
Enable custom attributesBooleanIf true, You will be able to set many custom attributes in your links.
Force folder restrictionBooleanIf true, You will be able to set a specific folder from where you can select your link.

You can access a draft or published versionof your links by providing the version parameter and the correct token type (eg. preview for draft, public for published).

PropertyDescription
idNumeric id of the referenced content entry
slugThe full_slug of the content entry
nameGiven name of the content entry
is_folderIs this content entry a folder (true/false)
parent_idParent folder numeric id
publishedIs this story published (true/false)
positionThe numeric position value of the content entry
uuidThe uuid of the content entry
Multiple uuidOne key per Story, where the key is the uuid of the story
is_startpageIS this story a startpage (true/false)

Returns the links object containing all links of one space. Use the version parameter and the correct token types to receive either draft and published or only published links.

Query ParameterDescription
token (required)Your public or preview token
starts_withFilter by full_slug. Can be used to retrieve all links form a specific folder. Examples: starts_with=de/beitraege, starts_with=en/posts
versionDefault: published. Possible values: draft, published
paginatedSet this to 1 if you want to retrieve the paginated results. With the parameters per_page and page, you can define the page size and page number
cvRead more about cache version at Cache invalidation
ATTENTION:

This API endpoint is not paged by default. Activate it using paginated=1.

It is also possible to set an anchor for internal links. The option can be enabled in the schema configuration as shown below.

Anchor options for internal links

Anchor options for internal links

If you're looking for anchor links for lets say headlines it would be something to be implemented in your frontend which can take the current string of your headline and transforms it to a specific entry. One example would be Anchorjs.

hint:

If you're referencing to linking to other entries, using the link field we will update the referenced entry right away. We've also introduced something called "Resolve Links" which allows your developer to access linked entries without additional query.


File

A single file upload input and access to the asset manager.

Asset

Assets in Storyblok are all files that you upload either using an image, file or multi-assets field or in the asset manager itself. Assets uploaded to Storyblok will be hosted on our infrastructure and delivered through our CDN with the best possible performance for you. Additionally, you can use our built-in image service to optimize and resize your images. Below you can find the MIME types for each asset type.

Asset TypeMIME Types
imageimage/x—png, image/png, image/gif, image/jpeg, image/svg+xml, image/webp
videovideo/*, application/mp4, application/x—mpegurl, application/vnd.apple.mpegurl, audio/webm
audioaudio/*
textapplication/msword, text/plain, application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document

The Asset Object

PropertyDescription
filenameFull path of the asset, including the file name
fileFile Object
short_filenameThe file name of the asset

You can now choose “Default Asset Folder” for the field type file which was previously only available for the type image.

Configuration OptionTypeDescription
Prepend https to urlBooleanIf true, it will prepend file url with https
Default asset folderDropdownYou can choose an asset folder where the assets should be assigned to
Default valueStringDefines the default value of the field

Multi-Asset

A multi-asset upload input, including a description for each and access to the asset manager.

Field TypeDescription
multiassetMulti-Assets; an upload field for multiple files

Additionally, you can use our built-in image service to optimize and resize your images. Below you can find the MIME types for each asset type.

Asset TypeMIME Types
imageimage/x—png, image/png, image/gif, image/jpeg, image/svg+xml, image/webp
videovideo/*, application/mp4, application/x—mpegurl, application/vnd.apple.mpegurl, audio/webm
audioaudio/*
textapplication/msword, text/plain, application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • Multi-Asset fields can be reordered via drag controls.
  • You can allow multiple image uploads in one field using the multi-asset field type.
Configuration OptionTypeDescription
Default asset folderDropdownYou can choose an asset folder where the assets should be assigned to
Multi-select options in Storyblok

Multi-select options in Storyblok


Single-Option

Single-Option is a dropdown of key/value pairs, Stories, Datasources, external JSONs, or Field Level Translation Languages.

HINT:

You can find an example of single-option as an external JSON here.

Field TypeDescription
optionSingle-Option; a single dropdown

SOURCE TYPE

There are several source types in the Single-Option Field which are as below:

Source types in Storyblok

Source types in Storyblok

Self

Configuration OptionTypeDescription
Hide empty optionBooleanIf true, it will hide the empty option
OptionsStringAdd name/value as options
Default ValueStringDefines the default value of the field

Stories

Configuration OptionTypeDescription
Use UID instead of IDBooleanRecommended to be checked (true), as UID is required for automatic link resolving
Path to folder of storiesStringIn case you have a multi-language folder structure you can add the {0}/ placeholder and the path will be adapted dynamically. Examples: {0}/categories/, {0}/{1}/categories/
Restrict to content typeDropdownYou can choose content types from the whitelist
Default valueStringDefines the default value of the field

Languages

Configuration OptionTypeDescription
Hide empty optionsBooleanIf true, it will hide the empty option
Default valueStringIf true, it will hide the empty option

Datasources

Configuration OptionTypeDescription
Hide empty optionBooleanIf true, it will hide the empty option
Internal datasourceDropdownSelect an internal database from the dropdown
Default value StringDefines the default value of the field

External JSON

Configuration OptionTypeDescription
Hide empty optionBooleanIf true, it will hide the empty option
URLStringAdd URL to the external JSON
Default valueStringDefines the default value of the field

Multi-Option

A multi-select option of key/value pairs, Stories, Datasources, external JSONs, or Field Level Translation Languages. 

HINT:

You can find an example of a multi-option as an external JSON here.

Field TypeDescription
optionsMulti-Options; a list of checkboxes

All the configuration options are similar to Single-Option. The only difference is that we get an additional configuration option in Multi-Option, which is as below:

Configuration OptionTypeDescription
Minimum & MaximumNumberDefines minimum & maximum numbers for the particular source.

The default value for multi-options

You can set a Default Value for multi-options with the following schema:

        
      [ "your_first_value", "your_second_value", "third", ... ]
    

Number

A number text field without formatting. 

Configuration OptionTypeDescription
Default valueStringDefines the default value of the field
hint:

You can convert string to JSON function


Markdown

Write markdown with a text area and additional formatting options.

Configuration OptionTypeDescription
Rich-text as defaultBooleanEnable rich markdown view by default (true/false); Only for type: markdown
Allow empty paragraphsBooleanEnables the allotment of empty paragraphs.
Customize toolbarBooleanEnables a list of options from the toolbar, like Bold, Italic, Code-block, H1, H2, H3, H4, H5, Unordered list, Ordered list, Quote, Link, Image, Help, Enlarge
Maximum charactersNumberSet the max length of the input string; Only for type: text, textarea, markdown
Enable RTL (Right to left)BooleanEnable global RTL for this field
Default valueStringDefines the default value of the field
hint:

Check out the npm module that lets you convert Markdown and HTML into Storyblok's Richtext field format.

There is also an example of how to use it with our migration CLI to transform fields.


Richtext

A multi-line field with formatting options that results in a JSON format. Storyblok comes with a powerful Richtext editor that saves your content in a structured JSON format. You can customize the toolbar for each field individually and even let the user insert Storyblok blocks. If you have written your content in Markdown you can import it using the toolbar button "Paste from Markdown".

Configuration OptionTypeDescription
Customize toolbarBooleanEnables a list of options from the toolbar, like Bold, Italic, Code-block, H1, H2, H3, H4, H5, Unordered list, Ordered list, Quote, Link, Image, Help, Enlarge, Emoji, Text coloring, Undo/Redo, Subscript, Superscript, Anchor
CSS class options (label/value)StringAdd name/value as options
Allow only specific components to be insertedBooleanIf enables, get three options to select from: - Component(s) - Folder(s) - Tag(s) Get a dropdown for Component and Component folder whitelist
Allow links to be open in a new tabBooleanIf enables, you can set links to be open in a new tab on the link modal.
Enable custom attributes for linksBooleanIf enables, you can add an ID in the link modal.
Customize the Richtext editor of Storyblok

Customize the Richtext editor of Storyblok

Features

  • Customizable Toolbar: Bold, Italic, Strikethrough, Underline, Inline-code, Code-block, Paragraph, H1, H2, H3, H4, H5, H6, Unordered list, Ordered list, Quote, Horizontal rule, Link, Image, Components, Paste Markdown, Emoji, Text coloring, Undo/Redo, Subscript, Superscript, Anchor
  • Clean JSON Output
  • JSON to HTML converter included in SDKs
  • Advanced link dialog with "New window" option and asset link function
  • Advanced image dialog with alt-tag and title definition
  • Component insertion with allowlist option
  • Paste from Markdown import function
  • Auto-height and sticky-toolbar
  • Works with export and import app
  • Code-language selector of code-block
hint:

Read more at the documentation of the Richtext field.



Table

It is easy to use field type to manage tables.

Table field types on Storyblok

Table field types on Storyblok

Features

  • Add, move or delete rows and columns
  • Outputs structured JSON
  • Allows multi-line text
  • Works with translation export and import

Developer documentation

The table field type stores its information as structured JSON and you need to take care of the rendering of the HTML.

Following an example:

        
      {
  "plugin": "translateable-table",
  "thead": [
    {
      "value": "Head1"
    },
    {
      "value": "Head2"
    }
  ],
  "tbody": [
    {
      "component": "_table_row",
      "body": [
        {
          "component": "_table_col",
          "value": "one"
        },
        {
          "component": "_table_col",
          "value": "two"
        }
      ]
    }
  ]
}
    

In a template language like Liquid you could write something like the following to render the table:

        
      <table>
  <thead>
    <tr>
      {% for th in content.thead %}
        <th>{{ th.value }}</th>
      {% endfor %}
    </tr>
  </thead>
  <tbody>
    {% for tr in content.tbody %}
      <tr>
        {% for td in tr.body %}
          <td>{{ td.value }}</td>
        {% endfor %}
      </tr>
    {% endfor %}
  </tbody>
</table>
    

Blocks

Blocks is a field to interleave other components in your current one, a field to allow nesting of Bloks.

Configuration OptionTypeDescription
Allow only specific components to be insertedBooleanIf enables, get three options to select from: - Component(s) - Folder(s) - Tag(s) Get a dropdown for Component and Component folder whitelist
Allowed maximumNumberDefines the maximal number of allowed characters in the field

This type of component lives only within a Story and other Blocks, such as Hero, Grid, and Full-Width Image. You can’t create new Stories from this as it is only a part of one Story. To use them in one content type you will need to create a field of the type blocks that allows the nesting of components.

        
      {
    "story": {
    "uuid": "ac0d2ed0-e323-43ca-ae59-5cd7d38683cb",
    "name": "My third post",
    "slug": "my-third-post",
    "full_slug": "posts/my-third-post",
    "content": {
-      "component": "your_content_type",
+      "component": "page",
        // fields you define for your content type
+      "body": [ // also a field you defined (type blocks)
+         {
+            "component": "teaser",
+            "headline": "My headline Content",
+            // fields you define for your blok
+         }
        ]
    },
    ...
}
    
TypeExamples
Content TypesPost, Authors, Product, Page, Team Members, FAQ article,
BloksHero, Grid, Section, Newsletter Section, Chapter, Full Width Image, Slider

Nestable blocks

Every block in Storyblok can have child blocks. If you define a block as nestable, then the editor of the content can position that block in a nestable area.

Usually, root blocks like pages, articles and products aren’t defined as nestable, as they are designed to build the root of your content structure. Read more on “What is a root block?”.

Group

Group field allows you to group fields in a section (no input possibility).

PropertyDescription
group_idAlternates group id (uuid string)
Configuration optionDescription
Section itemsThis is the list of all the fields of components you are in and which will be included in the group and which can be collapsed in the content editor

Component Folders

A component folder can be used to group components together. Each component can have only one component folder. However, you can add multiple Component tags to assign them to blocks and richtext field-types.

Component Tags

Component tags can be used in the blocks and richtext field-types. To create Component tags, go to the Block Library, and create new Component tags from there. Component tags can restrict the type of blocks and how they can be nested.

create-component-tags

Component tags examples and where to create new Component tags

Component tags can restrict the type of blocks and how they can be nested. To do so, Component tags should be used with the option Allow only specific components to be inserted.

component-tags-specific-nestable-components

Component tags with an option "Allow only specific components to be inserted"

The Component Object

PropertyDescription
component_group_uuidThe component folder uuid of the component

The Component Folder Object

PropertyDescription
idNumericc Unique ID
nameName of the group
uuidUuid of the group

Retrieve one Component Folder

Returns a single, fully loaded component folder object by providing a specific numeric id.

Retrieve multiple Component Folders 

Returns an array of component folder objects. The response of this endpoint is not paginated and you will retrieve all component folders.

Create a Component Folder

PropertyDescription
component_groupYour full component folder object
component_group[name]The component folder name is required

Delete a Component Folder

Delete any component folder using its numeric id.

Conditional Fields

Plugins aka Custom Field Type

A custom field type is a field type (plugin) that can be created by you or your developer to fulfil special requirements, that can't be fulfilled by the default set of the field types. The common sample is the integration with 3rd party services as e-shops or image services as Cloudinary.

learn:

Read the plugins documentation to learn how to create your own custom field type.

Presets

A preset defines the sample data of the component and each component may have defined a list of multiple presets. This feature should be used to guide your content creator in the process of creating new stories as they don't have to start always with empty components. They may choose one of the presets and tweak the data of it. Only a user with developer rights may create/edit preset.

hint:

You are able to define presets to both types of components - Content Types and Bloks.

Example use case

Let's say we have a teaser component with three different design variants. 

  1. Teaser with background image
  2. Teaser with background colour and text
  3. Teaser with a call to action button

We could define three different components in Storyblok or we can define a component called Teaser with different options. The single-component approach can be difficult to understand for a content creator without enough experience. To make the process easier, we can define three presets for those three variants and let the content creator choose the preset in the creation process. This will add a component with pre-filled values into the Story.

Shown list of defined presets for a component/story from example use case

Shown list of defined presets for a component/story from example use case

How to define Preset?

Only developers can create and edit the Presets. If the developer opens the Story in the Content Editor, he/she can see the Define schema button and next to it a dropdown arrow. The Define Preset button is hidden in this dropdown. By using the Define preset button a preset overlay is open, where you can define the Name of the preset and see the existing presets plus which one is selected as the default one for the component. After filling in the name of the preset and clicking the Add preset button, the preset is created in the component.

Showing where to find presets

Showing where the Define Preset button is

hint:

Each component can have one preset set as default.

You may always edit the preset by clicking on the name of the preset in the list of existing presets. This will open for you the following options.

OptionDescription
NameInput field where you can change the name of preset.
Screenshot uploadYou can upload a preview image of the preset.
Fill preset with current contentOverride data of the preset with current values from the content editor.
DeletePermanently deletes the preset from the list of presets.
hint:

We recommend uploading a preview image to preset. This makes the work of the content creator much easier.

  • Presets can be also managed using the Management API. Read more about it in the MAPI Docs.