Fields

A field is a content input. Storyblok has fields for different types of content. Stories and blocks are made up of fields.

All field types (except group) contain generic configuration options:

• 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 field-level translations is enabled (not applicable to block or group fields)
• Default value (string): Initial value when the field, block, or story is created (not applicable to asset, multi-asset, link, table, group, or plugin fields)

Conditional fields are fields that can appear, disappear, or be required based on the value of other fields (e.g. “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; choose a conditional setting (if all or any of the following conditions are true); and choose whether to hide, show, or mark as required a field.

The following fields and field configurations are available.

Asset (Single or Multi)

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

• Allow external URL (boolean): Display an input to link to a file externally
• Filetypes (select): Restrict uploads to specific filetypes
• Default assets folder (select): Define a starting location when opening the asset browser

Blocks

An input to add nested blocks.

• Allowed minimum (number): Enforce a lower limit on the number of blocks
• Allowed maximum (number): Enforce an upper limit on the number of blocks
• Allow only specific components to be inserted (boolean): Restrict the available blocks by component type, tag, or folder

Boolean

A toggle stored as true or false, defaulting to false.

• Inline label (boolean): Display label beside toggle

Date/time

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

• Disable time selection (boolean): Restrict input to only date

Group

A widget that opens and closes by a toggle to reveal or hide other fields. The group field only affects the editor interface and has no affect on the API response. From the field editor, select fields to include in the group.

Link

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

• Restrict to content types (boolean): Restrict internal links to certain content types (enabling this option will reveal a drop-down to select content types)
• Enable email field (boolean): Allow an email input
• Enable asset selection (boolean): Allow an asset uploader/selector
• Enable anchor field on internal link (boolean): Display a text input to manually define link IDs (e.g. 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 to define target as either _self or _blank
• Enable custom attributes (boolean): Display a form to add custom properties (such as title and rel) to the link object
• Force folder restriction (boolean): Restrict internal links to a a specific folder in your space (enabling this option will reveal a text input to define the folder)

Markdown

A text input for formatted text stored as Markdown.

• 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 will reveal a multi-select input)
• Maximum characters (number): Set a hard limit on the length of text in the input
• Enable RTL (boolean): Allow right-to-left formatting

Number

A number input.

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

A dropdown to select one or more items from a list. Options can be key–value pairs, stories, datasources, languages, or properties from an API.

• 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

The default value should be defined as an array (e.g. ["red","green"]).

If the properties come from an API, they should be served as a JSON array of objects, each with value and key properties with strings as their values, e.g.:

[
  {
    "value": "key_1",
    "name": "This is the item: 1"
  },
  {
    "value": "key_2",
    "name": "This is the item: 2"
  }
]

The value property will be the value delivered in the story payload. name will be the label in the editor interface.

Plugin

An extendable, customizable input. For more information, see the field plugins documentation.

References

Links to stories in the same space.

• Path to folder of stories (string): Limit the available stories to a folder
• Restrict to content type (select): Limit the available stories by content type(s)
• Enable advanced search (boolean): Enable search with filtering, sorting, and pagination
• Appearance (radio): Display stories as a link (more concise) or a card (more illustrative) in the selector that appears in the editor interface
• Minimum (number): Enforce a lower limit on the number of references
• Maximum (number): Enforce an upper limit on the number of references

Rich text

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

• 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 will reveal a menu to select formatting options)
• Allow only specific components to be inserted (boolean): Restrict blocks allowed in rich text composing (enabling this option will reveal 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 to define target as either _self or _blank
• Enable custom attributes (boolean): Display a form to add custom properties (such as title and rel) to the link object

• @storyblok/richtext Opens in new tab

  A custom resolver for the Storyblok rich text field to be used in JavaScript projects.

• storyblok/php-tiptap-extension Opens in new tab

  Storyblok PHP Tiptap Extension (co-created with SensioLabs, the creators of Symfony) to be used in PHP projects.

Table

A simple table editor that allows you to insert, move, and delete a flexible number of columns and rows and insert values.

The API returns this field separated by thead (the first row) and tbody (the following rows) and adds a component identifier to differentiate between _table_head, _tablerow, and _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"
},

Text

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

• Maximum characters (number): Limit the allowed number of characters
• Regex validation (string): Disable saving unless input matches a regex pattern (e.g. two words)
• RTL (boolean): Direction of text

Textarea

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

• Maximum characters (number): Limit the allowed number of characters
• Regex validation (string): Disable saving unless input matches a regex pattern (e.g. email)
• RTL (boolean): Direction of text

Deprecated fields

The following fields are deprecated:

• Image
• File