Field Types

Blockstudio provides a variety of field types for building block interfaces.

Guide: Field Patterns CookbookPractical recipes: conditional groups, smart selects, repeaters, and queryable storage.

General Properties

All fields share these common properties:

Property	Type	Description
`id`	string	Unique identifier for the attribute
`type`	string	The field type
`label`	string	Display label shown in the editor
`description`	string	Description text shown below the label
`default`	mixed	Default value for the field
`fallback`	mixed	Fallback value when field is empty
`help`	string	Help text displayed below the field
`hidden`	boolean	Hide the field from the UI
`switch`	boolean	Display a toggle that can disable the field. Defaults to `false`.
`conditions`	array	Conditional logic rules

attributes

Renders data attribute inputs.

{
  "type": "attributes"
}

Properties

Property	Type	Description
`default`	`array`	Default value that should be applied when first adding the block.
`fallback`	`array`	Fallback value that that will display when field value is empty.
`link`	`boolean`	Enables link selection from dropdown.
`media`	`boolean`	Enables media selection from dropdown.

checkbox

Renders a set of checkbox inputs.

{
  "type": "checkbox",
  "options": [
    {
      "value": "option1",
      "label": "Option 1"
    },
    {
      "value": "option2",
      "label": "Option 2"
    }
  ]
}

Properties

Property	Type	Description
`default`	`array \| string \| number`	Default value that should be applied when first adding the block.
`fallback`	`array \| string \| number`	Fallback value that that will display when field value is empty.
`options`	`array`	Options to choose from.
`returnFormat`	`string`	Specifies the return format value.
`populate`	`object`

classes

Renders a field to select CSS classes.

{
  "type": "classes"
}

Properties

Property	Type	Description
`default`	`string`	Default value that should be applied when first adding the block.
`fallback`	`string`	Fallback value that that will display when field value is empty.
`tailwind`	`boolean`	Whether to enable Tailwind classes for this input field.

code

Renders a code editor.

{
  "type": "code"
}

Properties

Property	Type	Description
`default`	`string`	Default value that should be applied when first adding the block.
`fallback`	`string`	Fallback value that that will display when field value is empty.
`autoCompletion`	`boolean`	Whether to enable autocompletion or not.
`foldGutter`	`boolean`	Whether to show the fold gutter or not.
`height`	`string`	The height of the editor.
`language`	`string`	The language to use for syntax highlighting.
`lineNumbers`	`boolean`	Whether to display line numbers or not.
`maxHeight`	`string`	The maximum height of the editor.
`minHeight`	`string`	The minimum height of the editor.
`popout`	`boolean`	Whether to show a button that opens the editor in a popup window.

color

Renders a color palette and color picker.

{
  "type": "color",
  "options": [
    {
      "value": "option1",
      "label": "Option 1"
    },
    {
      "value": "option2",
      "label": "Option 2"
    }
  ]
}

Properties

Property	Type	Description
`options`	`array`
`populate`	`object`
`clearable`	`boolean`	Whether the palette should have a clearing button or not.
`disableCustomColors`	`boolean`	Whether to allow custom color or not.

date

Renders a date picker.

{
  "type": "date"
}

Properties

Property	Type	Description
`default`	`string`	Default value that should be applied when first adding the block.
`fallback`	`string`	Fallback value that that will display when field value is empty.
`startOfWeek`	`number`	The day that the week should start on. 0 for Sunday, 1 for Monday, etc.

datetime

Renders a date and time picker.

{
  "type": "datetime"
}

Properties

Property	Type	Description
`default`	`string`	Default value that should be applied when first adding the block.
`fallback`	`string`	Fallback value that that will display when field value is empty.
`is12Hour`	`boolean`	Whether we use a 12-hour clock. With a 12-hour clock, an AM/PM widget is displayed and the time format is assumed to be MM-DD-YYYY (as opposed to the default format DD-MM-YYYY).

files

Renders a button to the media library. Picked items can be reordered inline.

{
  "type": "files",
  "min": 0,
  "max": 100,
  "multiple": false
}

Properties

Property	Type	Description
`default`	`array \| object \| number`	Default value that should be applied when first adding the block.
`fallback`	`array \| object \| number`	Fallback value that that will display when field value is empty.
`addToGallery`	`boolean`	If true, the gallery media modal opens directly in the media library where the user can add additional images. If false the gallery media modal opens in the edit mode where the user can edit existing images, by reordering them, remove them, or change their attributes. Only applies if gallery === true.
`allowedTypes`	`array \| string`	Array with the types of the media to upload/select from the media library. Each type is a string that can contain the general mime type e.g: 'image', 'audio', 'text', or the complete mime type e.g: 'audio/mpeg', 'image/gif'. If allowedTypes is unset all mime types should be allowed.
`gallery`	`boolean`	If true, the component will initiate all the states required to represent a gallery. By default, the media modal opens in the gallery edit frame, but that can be changed using the addToGalleryflag.
`max`	`number`	Maximum amount of files that can be added.
`min`	`number`	Minimum amount of files that can be added.
`multiple`	`boolean`	Whether to allow multiple selections or not.
`size`	`boolean`	Adds a media size dropdown to the field.
`textMediaButton`	`string`	Media button text.
`title`	`string`	Title displayed in the media modal.
`returnFormat`	`string`	Specifies the return format value.
`returnSize`	`string`	The media size to return when using the URL return format.

gradient

Renders a gradient palette and gradient picker

{
  "type": "gradient",
  "options": [
    {
      "value": "option1",
      "label": "Option 1"
    },
    {
      "value": "option2",
      "label": "Option 2"
    }
  ]
}

Properties

Property	Type	Description
`options`	`array`
`populate`	`object`
`clearable`	`boolean`	Whether the palette should have a clearing button or not.
`disableCustomGradients`	`boolean`	Whether to allow custom color or not.

group

Renders multiple fields in an (optionally) collapsible container.

{
  "type": "group"
}

Properties

Property	Type	Description
`title`	`string`	Title text. It shows even when the component is closed.
`opened`	`boolean`	When set to true, the component will remain open regardless of the initialOpen prop and the
`initialOpen`	`boolean`	Whether or not the panel will start open.
`scrollAfterOpen`	`boolean`	Scrolls the content into view when visible.
`class`	`string`	Custom CSS class that will be applied to the group.
`style`	`object`	Custom CSS styles that will be applied to the group.
`attributes`	`array`	Accepts all other field types besides another tabs.

icon

Renders an SVG icon from an icon set.

{
  "type": "icon"
}

Properties

Property	Type	Description
`default`	`object`	Default value that should be applied when first adding the block.
`fallback`	`object`	Fallback value that that will display when field value is empty.
`sets`	`array \| string`	Which icon set to include. Leave empty to include all.
`subSets`	`array \| string`	Which sub icon set to include. Leave empty to include all.
`returnFormat`	`string`	The format to return the icon in.

link

Renders a link control to choose internal or external links.

{
  "type": "link"
}

Properties

Property	Type	Description
`default`	`object`	Default value that should be applied when first adding the block.
`fallback`	`object`	Fallback value that that will display when field value is empty.
`hasRichPreviews`	`boolean`	Whether rich previews should be shown when adding an URL.
`noDirectEntry`	`boolean`	Whether to allow turning a URL-like search query directly into a link.
`noURLSuggestion`	`boolean`	Whether to add a fallback suggestion which treats the search query as a URL.
`opensInNewTab`	`boolean`	Adds a toggle control to the link modal.
`showSuggestions`	`boolean`	Whether to present suggestions when typing the URL.
`textButton`	`string`	Custom text that should be displayed inside the link button.
`withCreateSuggestion`	`boolean`	Whether to allow creation of link value from suggestion.

message

Renders a message with custom content.

{
  "type": "message"
}

Properties

Property	Type	Description
`default`	`string`	Default value that should be applied when first adding the block.
`fallback`	`string`	Fallback value that that will display when field value is empty.
`value`	`string`	The message to display. Block and attribute data is available in bracket syntax, e.g.: `{block.title}` or `{attributes.text}`

number

Renders a number input.

{
  "type": "number",
  "min": 0,
  "max": 100,
  "step": 1
}

Properties

Property	Type	Description
`default`	`number`	Default value that should be applied when first adding the block.
`fallback`	`number`	Fallback value that that will display when field value is empty.
`dragDirection`	`string`	Determines the drag axis to increment/decrement the value.
`dragThreshold`	`number`	If isDragEnabled is true, this controls the amount of px to have been dragged before the value changes.
`hideHTMLArrows`	`boolean`	If true, the default input HTML arrows will be hidden.
`isShiftStepEnabled`	`boolean`	If true, enables mouse drag gesture to increment/decrement the number value. Holding SHIFT while dragging will increase the value by the shiftStep.
`max`	`number`	The maximum value length.
`min`	`number`	Minimum value length.
`required`	`boolean`	If true enforces a valid number within the control’s min/max range. If false allows an empty string as a valid value.
`shiftStep`	`number`	Amount to increment by when the SHIFT key is held down. This shift value is a multiplier to the step value. For example, if the step value is 5, and shiftStep is 10, each jump would increment/decrement by 50.
`step`	`number`	Amount by which the value is changed when incrementing/decrementing. It is also a factor in validation as value must be a multiple of step (offset by min, if specified) to be valid. Accepts the special string value any that voids the validation constraint and causes stepping actions to increment/decrement by 1.

radio

Renders a set of radio inputs.

{
  "type": "radio",
  "options": [
    {
      "value": "option1",
      "label": "Option 1"
    },
    {
      "value": "option2",
      "label": "Option 2"
    }
  ]
}

Properties

Property	Type	Description
`default`	`string \| number`	Default value that should be applied when first adding the block.
`fallback`	`string \| number`	Fallback value that that will display when field value is empty.
`options`	`array`	Options to choose from.
`returnFormat`	`string`	Specifies the return format value.
`populate`	`object`

range

Renders a range input to set a numerical value between two points.

{
  "type": "range",
  "min": 0,
  "max": 100,
  "step": 1
}

Properties

Property	Type	Description
`default`	`number`	Default value that should be applied when first adding the block.
`fallback`	`number`	Fallback value that that will display when field value is empty.
`allowReset`	`boolean`	If this property is true, a button to reset the slider is rendered.
`initialPosition`	`number`	The slider starting position, used when no value is passed. The initialPosition will be clamped between the provided min and max prop values.
`isShiftStepEnabled`	`boolean`	If true, enables mouse drag gesture to increment/decrement the number value. Holding SHIFT while dragging will increase the value by the shiftStep.
`marks`	`array`	Renders a visual representation of step ticks. Custom mark indicators can be provided by an Array.
`max`	`number`	The maximum value length.
`min`	`number`	Minimum value length.
`railColor`	`string`	CSS color string to customize the rail element’s background.
`resetFallbackValue`	`number`	The value to revert to if the Reset button is clicked (enabled by allowReset)
`separatorType`	`string`	Define if separator line under/above control row should be disabled or full width. By default it is placed below excluding underline the control icon.
`shiftStep`	`number`	Amount to increment by when the SHIFT key is held down. This shift value is a multiplier to the step value. For example, if the step value is 5, and shiftStep is 10, each jump would increment/decrement by 50.
`showTooltip`	`boolean`	Forcing the Tooltip UI to show or hide. This is overridden to false when step is set to the special string value any.
`step`	`number`	Amount by which the value is changed when incrementing/decrementing. It is also a factor in validation as value must be a multiple of step (offset by min, if specified) to be valid. Accepts the special string value any that voids the validation constraint and causes stepping actions to increment/decrement by 1.
`trackColor`	`string`	CSS color string to customize the track element’s background.
`withInputField`	`boolean`	Determines if the input number field will render next to the RangeControl. This is overridden to false when step is set to the special string value any.

select

Renders a select input with support for single or multiple selections.

{
  "type": "select",
  "options": [
    {
      "value": "option1",
      "label": "Option 1"
    },
    {
      "value": "option2",
      "label": "Option 2"
    }
  ],
  "multiple": false
}

Properties

Property	Type	Description
`default`	`array \| string \| number`	Default value that should be applied when first adding the block.
`fallback`	`array \| string \| number`	Fallback value that that will display when field value is empty.
`multiple`	`boolean`	If true, multiple options can be selected. "stylisedUi" will be automatically enabled.
`options`	`array`	Options to choose from.
`returnFormat`	`string`	Specifies the return format value.
`populate`	`object`
`stylisedUi`	`boolean`	Renders a stylised version of a select with the ability to search through items.
`allowNull`	`boolean \| string`	Allows the user to select an empty choice. If true, the label will be empty, otherwise the option will render the specified string.
`allowReset`	`boolean`	If this property is true, a button to reset the select is rendered.

tabs

Renders a tabbed interface for grouping fields.

{
  "type": "tabs"
}

Properties

Property	Type	Description
`tabs`	`array`	The tabs to display.

text

Renders a single line text input.

{
  "type": "text",
  "min": 0,
  "max": 100
}

Properties

Property	Type	Description
`default`	`string`	Default value that should be applied when first adding the block.
`fallback`	`string`	Fallback value that that will display when field value is empty.
`max`	`number`	The maximum value length.
`min`	`number`	Minimum value length.

textarea

Renders a textarea input.

{
  "type": "textarea",
  "min": 0,
  "max": 100,
  "rows": 4
}

Properties

Property	Type	Description
`default`	`string`	Default value that should be applied when first adding the block.
`fallback`	`string`	Fallback value that that will display when field value is empty.
`max`	`number`	The maximum value length.
`min`	`number`	Minimum value length.
`rows`	`number`	The number of rows the textarea should contain.

toggle

Renders a true/false toggle.

{
  "type": "toggle"
}

Properties

Property	Type	Description
`default`	`boolean`	Default value that should be applied when first adding the block.
`fallback`	`boolean`	Fallback value that that will display when field value is empty.

repeater

Renders a set of fields that can be repeated.

{
  "type": "repeater",
  "min": 0,
  "max": 100
}

Properties

Property	Type	Description
`min`	`number`	Minimum amount of rows.
`max`	`number`	Maximum amount of rows.
`textButton`	`string`	Text for the add button.
`textMinimized`	`string \| object`	Text that will be displayed when rows are minimized.
`textRemove`	`string \| boolean`	Text to display in alert when removing repeater row.
`attributes`	`array`	Accepts all other field types besides another tabs.

richtext

Attribute field for RichText fields.

{
  "type": "richtext"
}

Properties

Property	Type	Description
`default`	`string`	Default value that should be applied when first adding the block.
`fallback`	`string`	Fallback value that that will display when field value is empty.

unit

Renders a number input with a unit dropdown.

{
  "type": "unit"
}

Properties

Property	Type	Description
`default`	`string`	Default value that should be applied when first adding the block.
`fallback`	`string`	Fallback value that that will display when field value is empty.
`disableUnits`	`boolean`	If true, the unit select field is hidden.
`isPressEnterToChange`	`boolean`	If true, the ENTER key press is required in order to trigger an onChange. If enabled, a change is also triggered when tabbing away.
`isResetValueOnUnitChange`	`boolean`	If true, and the selected unit provides a default value, this value is set when changing units.
`isUnitSelectTabbable`	`boolean`	Determines if the unit select field is tabbable.
`units`	`array`

wysiwyg

Renders a WYSIWYG editor.

{
  "type": "wysiwyg"
}

Properties

Property	Type	Description
`default`	`string`	Default value that should be applied when first adding the block.
`fallback`	`string`	Fallback value that that will display when field value is empty.
`toolbar`	`object`	The toolbar configuration for the editor.

On this page