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
color
, you can use named colors instead of fixed hex values.
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'