Skip to content

Fields

A field is a content input. Storyblok has a variety of fields for different types of content. Stories and blocks consist of fields.

All field types, except group, contain generic configuration options:

Option Type Description
Required boolean Disable saving when the field is empty
Display name string Label for the field in the Visual Editor
Field name string The key for the field on the API
Description string Explanatory text under the field in the editor
Show description as tooltip boolean Replace the description text with a tooltip
Translatable boolean Allows translation when you enable field-level translations (not applicable to blocks fields)
Default value string Initial value when an editor adds the block (not applicable to asset, link, table, or plugin fields)

The following fields types and field configurations are available.

An input to upload, browse, and select files hosted on Storyblok’s infrastructure.

Option Type Description
Allow external URL boolean Display an input to link to a file externally
Filetypes select Restrict uploads to specific file types supported in the Asset library.
Default assets folder select Define a starting location when opening the asset browser

An input to add nested blocks.

Option Type Description
Allowed minimum number Enforce a lower limit on the number of blocks
Allowed maximum number Enforce an upper limit on the number of blocks
Manage access to nestable blocks boolean Restrict which nestable blocks users can insert. Once enabled, allow or deny access to selected blocks, block folders, and block tags.

A toggle stored as true or false (defaults to false).

Option Type Description
Inline label boolean Display label beside toggle

A picker for a date or timestamp stored as an ISO 8601 date value (YYYY-MM-DD HH:MM).

Option Type Description
Disable time selection boolean Restrict input to only date

A widget that opens and closes by a toggle to reveal or hide other fields. In the field editor, select fields to include in the group.

The group field is only a visual aid for organizing fields in the Visual Editor. It doesn’t affect the API response.

A dynamic input to create a link to a website, story, asset, or email.

Option Type Description
Restrict to content types boolean Restrict internal links to specific content types. Enabling this option reveals a drop-down to select content types.
Enable email field boolean Allow an email input
Enable asset selection boolean Allow an asset upload popup
Enable anchor field on internal link boolean Display a text input that lets editors manually define link IDs (such as example.com#example-id) on internal links
Allow links to open in new tab boolean Display an “Open in new window” toggle below the link field. When an editor interacts with the toggle, the link object includes a target with a value of _self or _blank.
Enable custom attributes boolean Display a form that lets editors add custom properties (such as title and rel) to the link object. When an editor uses the form and saves the story, the link object includes the properties. The property values can be empty strings.
Force folder restriction boolean Restrict internal links to a specific folder. Enabling this option reveals a text input that lets editors define the folder.

The API response represents a link as an object with the following properties:

Property Description
id The UUID of the linked story. Only available for story links.
url The URL, email address, or an asset URL an editor provides. Empty for story links.
linktype story, url, asset, or email, depending on which link type the editor selected. linktype determines whether to follow id or url.
fieldtype Always multilink.
cached_url For story links, the linked story’s full_slug on the latest save. If the linked story moves or its slug changes, cached_url keeps the old value. For the other link types, returns the same value as url.
email The email address. Only available for email links.
target _self or _blank. Only available if an editor interacts with the toggle.

To resolve links at request time when you retrieve multiple stories or a single story, add the resolve_links parameter to the request.

The response lists the linked stories in the links array. The value of resolve_links determines how much data the API returns for each linked story:

Value Response contains
link Routing properties of the linked story, including full_slug, path, real_path, parent_id, alternates, is_folder, is_startpage, published, and position.
url The minimum data necessary to resolve the linked story’s path.
story The complete story object, including its content.

To resolve the links inside linked stories, add resolve_links_level=2 to the request. Both endpoints support up to two levels.

The Allow links to open in new tab option adds an “Open in new window” toggle to the link field. The link object includes target only after an editor uses the toggle and saves the story. After that, the link object always includes target, even when an editor turns the toggle off:

Toggle state target value
Never used (default) Not included
On _blank
Off, after being on _self

For example, a story link with the toggle on:

"link": {
"id": "d334307e-cb01-4a1a-bf16-acfd3e41e13b",
"url": "",
"target": "_blank",
"linktype": "story",
"fieldtype": "multilink",
"cached_url": "landing"
}

A text input for formatted text stored as Markdown.

Option Type Description
Rich text as default boolean Display formatted text by default
Allow empty paragraphs boolean Preserve empty space between paragraphs
Customize toolbar boolean Configure the formatting options in the toolbar (enabling this option reveals a multi-select input)
Maximum characters number Set a hard limit on the length of text in the input
Enable RTL boolean Support right-to-left text direction

An input for whole or decimal numbers, such as a price or a quantity.

Option Type Description
Min value number Disable saving when input is below a limit
Max value number Disable saving when input is above a limit
Number of decimals number Define the number of allowed decimal places
Number of steps number Define an interval for the increment/decrement buttons on the number input

A drop-down that lets editors select one or more items from a list. Options can be key–value pairs, stories, datasources, languages, or properties from an API.

Option Type Description
Source select Define a source for the selection options
Minimum number Enforce a lower limit on the number of items
Maximum number Enforce an upper limit on the number of items

For single-option and multi-option fields, set a default value as follows:

Source Default value
Self The value as a plain string
Stories The story UUID as a plain string
Languages The language code (as defined in Settings → Internationalization)
Datasource The value as a plain string
External JSON A URL of a field plugin

For a single default value, enter the value, such as value_1. For multi-option fields, set one or more default values as an array of strings in double quotation marks, such as ["value_1", "value_3"].

When you choose Stories as a Source, you can restrict the stories available for selection to a specific folder. To apply this functionality, define the desired folder in the Path to folder of stories field.

A custom input that developers build and configure as a field plugin.

A picker to select one or more stories from the same space.

Option Type Description
Path to folder of stories string Restrict the stories available for selection to a specific folder
Restrict to content type select Restrict the available stories by content type
Enable advanced search boolean Enable search with filtering, sorting, and pagination
Appearance radio Display stories as a link or an illustrative card in the selector that appears in the Visual Editor
Minimum number Enforce a lower limit on the number of references
Maximum number Enforce an upper limit on the number of references

A text input for content with advanced and customizable formatting, stored as JSON.

Option Type Description
Maximum characters number Limit the allowed number of characters
Custom CSS class object Enable custom CSS classes with a display name and value
Customize toolbar items boolean Change the formatting options in the toolbar. Enabling this option reveals a menu to select formatting options.
Allow only specific components to be inserted boolean Restrict blocks allowed in the rich text editor. Enabling this option reveals a menu to select blocks.
Allow links to be open in a new tab boolean Display an “Open in new window” toggle in the link editor. When an editor interacts with the toggle, the link object includes a target with a value of _self or _blank.
Enable custom attributes boolean Display a form that lets editors add custom properties (such as title and rel) to the link object. When an editor uses the form and saves the story, the link object includes the properties. The property values can be empty strings.

The rich text field uses the Tiptap editor. To render rich text content in your app, use one of the following libraries:

A table editor to add, move, and delete rows and columns, and enter cell values.

The API returns the table field as an object with two arrays, thead for the first row and tbody for the remaining rows. Each item’s component property identifies it as _table_head, _table_row, or _table_col:

{
"tbody": [
{
"_uid": "86aa3186-0b5a-4260-a6d5-5f9a0b4d9484",
"body": [
{
"_uid": "1bdbf0fd-4163-4024-b110-114d781f1ba6",
"value": "Value 1",
"component": "_table_col"
},
{
"_uid": "8c815645-22e8-4a4a-a87a-b68eb4c63a78",
"value": "Value 2",
"component": "_table_col"
}
],
"component": "_table_row"
}
],
"thead": [
{
"_uid": "d91eb405-2bc7-4da8-9b4a-a99744b3ef9f",
"value": "Column 1",
"component": "_table_head"
},
{
"_uid": "5d615ffa-e2b8-4f79-88de-5a4bf08ee9a4",
"value": "Column 2",
"component": "_table_head"
}
],
"fieldtype": "table"
},

A text input for short strings, such as a product or author name.

Option Type Description
Maximum characters number Limit the allowed number of characters
Regex validation string Disable saving unless input matches a regex pattern (for example, an email address)
RTL boolean Support right-to-left text direction

A text input for a paragraph without formatting, such as a meta description or teaser text.

Option Type Description
Maximum characters number Limit the allowed number of characters
Regex validation string Disable saving unless input matches a regex pattern (for example, an email address)
RTL boolean Support right-to-left text direction

Conditional fields depend on the value of other fields. Based on that value, the Visual Editor shows or hides a conditional field, or marks it as required. For example, “Reveal the internal_title field only if the title field is empty, and make the internal_title field required.”

To create a conditional field, open the field editor. Select a conditional setting (if all or any of the following conditions are true), and choose whether to hide, show, or mark as required.

Storyblok deprecated the following fields:

  • Image
  • File

Was this page helpful?

What went wrong?

This site uses reCAPTCHA and Google's Privacy Policy (opens in a new window).Terms of Service (opens in a new window) apply.