Attributes - Field types

Last modified:

Checkbox


                                                    {
            "title": "Checkbox field",
            "blockstudio": {
              "attributes": [
                {
                  "id": "checkbox",
                  "type": "checkbox",
                  "label": "Checkbox",
                  "options": [
                    {
                      "value": "option-1",
                      "label": "Option 1"
                    },
                    {
                      "value": "option-2",
                      "label": "Option 2"
                    }
                  ]
                }
              ]
            }
          }
                                                                                                                                                                                                                
      
        

Renders a set of checkbox inputs.

Properties

default: string | number | boolean
Default value that should be applied when first adding the block.

options: object (label: string, value: string)
Options to choose from.

returnFormat: string (value | label | both)
Specifies the return format value.

populate: object

Color


                                                              {
            "title": "Color field",
            "blockstudio": {
              "attributes": [
                {
                  "id": "color",
                  "type": "color",
                  "label": "Color",
                  "options": [
                    {
                      "name": "red",
                      "value": "#f00",
                      "slug": "red"
                    },
                    {
                      "name": "white",
                      "value": "#fff",
                      "slug": "white"
                    }
                  ]
                }
              ]
            }
          }
                                                                                                                                                                                                      
      
        

Renders a color palette and color picker.

Properties

options: object (name: string, value: string, slug: string)

clearable: boolean
Whether the palette should have a clearing button or not.

disableCustomColors: boolean
Whether to allow custom color or not.

Date


                                                                        {
            "title": "Date field",
            "blockstudio": {
              "attributes": [
                {
                  "id": "date",
                  "type": "date",
                  "label": "Date"
                }
              ]
            }
          }
                                                                                                                                                                                            
      
        

Renders a date picker.

Properties

startOfWeek: number
The day that the week should start on. 0 for Sunday, 1 for Monday, etc.

Datetime


                                                                                  {
            "title": "Datetime field",
            "blockstudio": {
              "attributes": [
                {
                  "id": "datetime",
                  "type": "datetime",
                  "label": "Datetime"
                }
              ]
            }
          }
                                                                                                                                                                                  
      
        

Renders a date and time picker.

Properties

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.

Properties

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 (object | id)
Specifies the return format value.

Gradient


                                                                                                      {
            "title": "Gradient field",
            "blockstudio": {
              "attributes": [
                {
                  "id": "gradient",
                  "type": "gradient",
                  "label": "Gradient",
                  "options": [
                    {
                      "name": "JShine",
                      "value": "linear-gradient(135deg,#12c2e9 0%,#c471ed 50%,#f64f59 100%)",
                      "slug": "jshine"
                    },
                    {
                      "name": "Moonlit Asteroid",
                      "value": "linear-gradient(135deg,#0F2027 0%, #203A43 0%, #2c5364 100%)",
                      "slug": "moonlit-asteroid"
                    }
                  ]
                }
              ]
            }
          }
                                                                                                                                                              
      
        

Renders a gradient palette and gradient picker

Properties

options: object (name: string, value: string, slug: string)

clearable: boolean
Whether the palette should have a clearing button or not.

disableCustomGradients: boolean
Whether to allow custom color or not.

Group


                                                                                                                {
            "title": "Group field",
            "blockstudio": {
              "attributes": [
                {
                  "id": "group",
                  "type": "group",
                  "title": "Group",
                  "initialOpen": true,
                  "attributes": [
                    {
                      "id": "text",
                      "type": "text",
                      "label": "Text"
                    },
                    {
                      "id": "number",
                      "type": "number",
                      "label": "Number"
                    }
                  ]
                }
              ]
            }
          }
                                                                                                                                                    
      
        

Renders multiple fields in an (optionally) collapsible container.

Properties

title: string

opened: boolean

icon: string

initialOpen: boolean

attributes: object (id: string, type: string, label: string, help: string, conditions: array)
Accepts all other field types besides another group.

With and without ID


                            
          {
            "blockstudio": {
              "attributes": [
                {
                  "type": "group",
                  "label": "My group",
                  "attributes": [
                    {
                      "id": "message",
                      "type": "text",
                      "label": "My message"
                    }
                  ]
                }
              ]
            }
          }

                      
        

The code above will prevail the IDs of all inner attributes. For example, you can return the value of the text field using $a['message'] in your code. This is a great way to structure your attributes. As your block grows, you can easily move attributes to other groups without having to worry about changing the IDs.

It is also possible to prefix all attribute IDs inside the groups by applying an id key to the group field, prefixing all inner attribute IDs with the group ID.


                            
          {
            "blockstudio": {
              "attributes": [
                {
                  "id": "group",
                  "type": "group",
                  "label": "My group",
                  "attributes": [
                    {
                      "id": "message",
                      "type": "text",
                      "label": "My message"
                    }
                  ]
                }
              ]
            }
          }

                      
        

To access attributes inside groups with IDs, simply prepend the group ID following an _ to the inner attribute ID.


                            
          <h1><?php echo $attributes['group_message']; ?></h1>
          <h1><?php echo $a['group_message']; ?></h1>

It is also possible to access group values using the bs_get_group helper function.


                            
          <?php
          // bs_get_group($attributes, $groupName)
          $group = bs_get_group($a, 'group'); ?>

          <h1><?php echo $group['message']; ?></h1>

Icon


                                                                                                                          {
            "title": "Icon field",
            "blockstudio": {
              "attributes": [
                {
                  "id": "icon",
                  "type": "icon",
                  "label": "Icon"
                }
              ]
            }
          }
                                                                                                                                          
      
        

Renders an SVG icon from an icon set.

Properties

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.

Available sets and subsets

  • octicons
  • vscode-icons
  • remix-icons
    • design
    • buildings
    • development
    • health
    • business
    • logos
    • others
    • user
    • document
    • system
    • map
    • finance
    • device
    • weather
    • communication
    • editor
    • media
  • tabler-icons
  • simple-icons
  • flat-color-icons
  • bootstrap-icons
  • material-design-icons
    • two-tone
    • outlined
    • filled
    • round
    • sharp
  • box-icons
    • logos
    • solid
    • regular
  • ion-icons
  • heroicons
    • solid
    • outline
  • feather-icons
  • fontawesome-free
    • brands
    • solid
    • regular
  • grommet-icons
  • css-gg

                                                                                                                                    {
            "title": "Link field",
            "blockstudio": {
              "attributes": [
                {
                  "id": "link",
                  "type": "link",
                  "label": "Link"
                }
              ]
            }
          }
                                                                                                                                
      
        

Renders a link control to choose internal or external links.

Properties

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.

Number


                                                                                                                                              {
            "title": "Number field",
            "blockstudio": {
              "attributes": [
                {
                  "id": "number",
                  "type": "number",
                  "label": "Number"
                }
              ]
            }
          }
                                                                                                                      
      
        

Renders a number input.

Properties

default: string | number | boolean
Default value that should be applied when first adding the block.

dragDirection: string (n | e | s | w)
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


                                                                                                                                                        {
            "title": "Radio field",
            "blockstudio": {
              "attributes": [
                {
                  "id": "radio",
                  "type": "radio",
                  "label": "Radio",
                  "options": [
                    {
                      "value": "option-1",
                      "label": "Option 1"
                    },
                    {
                      "value": "option-2",
                      "label": "Option 2"
                    }
                  ]
                }
              ]
            }
          }
                                                                                                            
      
        

Renders a set of radio inputs.

Properties

default: string | number | boolean
Default value that should be applied when first adding the block.

options: object (label: string, value: string)
Options to choose from.

returnFormat: string (value | label | both)
Specifies the return format value.

populate: object

Range


                                                                                                                                                                  {
            "title": "Range field",
            "blockstudio": {
              "attributes": [
                {
                  "id": "range",
                  "type": "range",
                  "label": "Radio"
                }
              ]
            }
          }
                                                                                                  
      
        

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

Properties

default: string | number | boolean
Default value that should be applied when first adding the block.

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: object (label: string, value: number)
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 (none | fullWidth | topFullWidth)
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


                                                                                                                                                                            {
            "title": "Select field",
            "blockstudio": {
              "attributes": [
                {
                  "id": "select",
                  "type": "select",
                  "label": "Select",
                  "options": [
                    {
                      "value": "option-1",
                      "label": "Option 1"
                    },
                    {
                      "value": "option-2",
                      "label": "Option 2"
                    }
                  ]
                }
              ]
            }
          }
                                                                                        
      
        

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

Properties

default: string | number | boolean
Default value that should be applied when first adding the block.

multiple: boolean
If this property is added, multiple values can be selected.

options: object (label: string, value: string, disabled: boolean)
Options to choose from.

populate: object

stylisedUi: boolean
Renders a stylised version of a select with the ability to search through items.

Text


                                                                                                                                                                                      {
            "title": "Text field",
            "blockstudio": {
              "attributes": [
                {
                  "id": "text",
                  "type": "text",
                  "label": "Text"
                }
              ]
            }
          }
                                                                              
      
        

Renders a single line text input.

Properties

default: string | number | boolean
Default value that should be applied when first adding the block.

max: number
The maximum value length.

min: number
Minimum value length.

Textarea


                                                                                                                                                                                                {
            "title": "Textarea field",
            "blockstudio": {
              "attributes": [
                {
                  "id": "textarea",
                  "type": "textarea",
                  "label": "Textarea"
                }
              ]
            }
          }
                                                                    
      
        

Renders a textarea input.

Properties

default: string | number | boolean
Default value that should be applied when first adding the block.

max: number
The maximum value length.

min: number
Minimum value length.

rows: number
The number of rows the textarea should contain.

Toggle


                                                                                                                                                                                                          {
            "title": "Toggle field",
            "blockstudio": {
              "attributes": [
                {
                  "id": "toggle",
                  "type": "toggle",
                  "label": "Toggle"
                }
              ]
            }
          }
                                                          
      
        

Renders a true/false toggle.

Properties

default: string | number | boolean
Default value that should be applied when first adding the block.

Token


                                                                                                                                                                                                                    {
            "title": "Token field",
            "blockstudio": {
              "attributes": [
                {
                  "id": "token",
                  "type": "token",
                  "label": "Token",
                  "options": ["option-1", "option-2"]
                }
              ]
            }
          }
                                                
      
        

Renders a field similar to the “to” field in Mail on OS X. Tokens can be entered by typing them or selecting them from a list of suggested tokens.

Properties

maxLength: number
Maximum amount of tokens that can be added.

placeholder: string
Input placeholder if no tokes are selected.

options: object (label: string, value: string)
Options to choose from.

returnFormat: string (value | label | both)
Specifies the return format value.

Repeater


                                                                                                                                                                                                                              {
            "title": "Repeater field",
            "blockstudio": {
              "attributes": [
                {
                  "id": "repeater",
                  "type": "repeater",
                  "label": "Repeater",
                  "attributes": [
                    {
                      "id": "text",
                      "type": "text",
                      "label": "Text"
                    },
                    {
                      "id": "repeater",
                      "type": "repeater",
                      "label": "Repeater",
                      "min": 1,
                      "textButton": "Add repeater 1",
                      "attributes": [
                        {
                          "id": "text",
                          "type": "text",
                          "label": "Text"
                        },
                        {
                          "id": "repeater",
                          "type": "repeater",
                          "label": "Repeater",
                          "min": 1,
                          "max": 2,
                          "textButton": "Add repeater 2",
                          "attributes": [
                            {
                              "id": "number",
                              "type": "number",
                              "label": "Number",
                              "default": 10
                            },
                            {
                              "id": "repeater",
                              "type": "repeater",
                              "label": "Repeater",
                              "min": 2,
                              "max": 3,
                              "textButton": "Add repeater 3",
                              "attributes": [
                                {
                                  "id": "range",
                                  "type": "range",
                                  "label": "Range",
                                  "default": 50
                                }
                              ]
                            }
                          ]
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          }
                                      
      
        

Renders a set of fields that can be repeated.

Properties

min: number
Minimum amount of rows.

max: number
Maximum amount of rows.

attributes: object (id: string, type: string, label: string, help: string, conditions: array)
Accepts all other field types besides another group.

Wysiwyg


                                                                                                                                                                                                                                          {
              "title": "WYSIWYG field",
              "blockstudio": {
                "attributes": [
                  {
                    "id": "wysiwyg",
                    "type": "wysiwyg",
                    "label": "WYSIWYG",
                    "toolbar": {
                      "formats": {
                        "bold": true,
                        "italic": true,
                        "underline": true,
                        "strikethrough": true
                      }
                    }
                  }
                ]
              }
            }
                            
      
        

Renders a WYSIWYG editor.

Properties

toolbar: object
The toolbar configuration for the editor.