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.
Asset (single or multi)
Section titled “Asset (single or multi)”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 |
Blocks
Section titled “Blocks”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. |
Boolean
Section titled “Boolean”A toggle stored as true or false (defaults to false).
| Option | Type | Description |
|---|---|---|
| Inline label | boolean | Display label beside toggle |
Date/time
Section titled “Date/time”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. |
Link API response
Section titled “Link API response”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.
How target appears in the link object
Section titled “How target appears in the link object”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"}Markdown
Section titled “Markdown”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 |
Number
Section titled “Number”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 |
Option (single or multi)
Section titled “Option (single or multi)”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.
Plugin
Section titled “Plugin”A custom input that developers build and configure as a field plugin.
References
Section titled “References”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 |
Rich text
Section titled “Rich text”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:
@storyblok/richtext: a JavaScript resolver for Storyblok’s rich text field.- Storyblok PHP Tiptap extension: Tiptap extensions for Storyblok’s rich text field, co-created with SensioLabs, the creators of Symfony
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 |
Textarea
Section titled “Textarea”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
Section titled “Conditional fields”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.
Deprecated fields
Section titled “Deprecated fields”Storyblok deprecated the following fields:
- Image
- File
Was this page helpful?
This site uses reCAPTCHA and Google's Privacy Policy (opens in a new window).Terms of Service (opens in a new window) apply.
- Need help?Contact support (opens in a new window)
- Something isn’t right?Check system status (opens in a new window)
Get in touch with the Storyblok community