Field Editor Controls

Control types define the editing experience of fields in the Stackbit UI.

The UI offers several non-default editor controls which you can use. Each control is usable for specific fields types only.

For example, the control for a field of the enum type can be presented in multiple different ways. Today we use a simple dropdown box with several options to select from. The new Stackbit Studio defines new types of UI controls, mostly for the enum field type.

dropdown

Valid for field type: enum.

This is the default control for the enum field type. It shows a simple drop-down list of options.

- type: enum
  name: colorStyle
  controlType: 'dropdown'
  options:
    - label: Primary Color
      value: primary
    - label: Secondary Color
      value: secondary

button-group

Valid for field type: enum.

Useful for a short list of options that doesn't require a dropdown

- type: enum
  name: width
  label: Width
  group: design
  controlType: button-group
  options:
    - label: Narrow
      value: narrow
    - label: Wide
			value: wide
    - label: Full
			value: full

thumbnails

Valid for field type: enum.

This control is useful for selecting between options that can benefit from having a visual representation for each, e.g. different visual layouts for a component.

To define the images, set the thumbnail property for each item. The file path should be relative to the project root (these images are not published as public assets during the build, they are only used in the editor UI).

Here's an imaginary model using this control type:

name: FlexibleSection
...
fields:
	- type: enum
	  name: visualLayout
	  label: Layout
	  controlType: 'thumbnails'
	  options:
	    - value: content-left
	      label: Content on left, image on right
	      thumbnail: './images/content-left.png'
	    - value: content-right
	      label: Content on right, image on left
	      thumbnail: './images/content-right.png'
	    - value: content-top
	      label: Content on top, image at bottom
	      thumbnail: './images/content-top.png'

palette

Valid for field type: enum.

This control is useful for selecting color schemes for components from several fixed options.

This is a simpler alternative to using a thumbnails control. Rather than requiring you to create thumbnails, it lets you define items which mock each color scheme. Each iterm is rendered in the UI as a tile with specifiic colors for its background, text and border.

Here's how the control might look like in the UI:

As with any enum field, once a user selects any of the options it is the value of that option that is set as the field value. This value is always a string. In the example below, these values are: "style-a", "style-b", and so on. It is then the rendering component's responsibility to apply that named style.

The control adds the following properties to the options object to set the appearance of tiles:

• textColor
• backgroundColor
• borderColor - if not specified, no border will be drawn.

- type: enum
  name: look
  controlType: 'palette'
  options:
    - value: style-a
      textColor: '#FFFFFF'
      backgroundColor: '#000000'
    - value: style-b
      textColor: '#000000'
      backgroundColor: '...'
      borderColor: '#000000'
    # ...and so on

slider

Valid for field type: number.

This control type can be used on numeric fields that have a fixed range. The min and max properties of numeric fields must be set for this control to function.

You can also optionally define a step (the default is 1) and a unit denominator that will be displayed next the the current value. The unit has no effect on the actual stored value.

- type: number
  name: letterSpacing
  controlType: 'slider'
  min: 0
  max: 100
  step: 10
  unit: '%'

- type: number
  name: lineHeight
  controlType: 'slider'
  min: 100
  max: 200
  step: 20
  unit: 'px'