Component schema

Description of the component plugin schema

📘

Schema JSON changes in development

Changes saved to the schema.json file are not hot reloaded. The app builder must be refreshed.

Provides a number of attributes that determine the available options in the settings panel and how the component is displayed in the component tree.

Required fields are marked by an asterisk.

PropertyTypeDescription
name*stringA unique name for your component.
friendlyName*stringThe name that is displayed in the app builder.
icon*stringThe name of the icon that is shown in the component tree.

A full list of the available icons can be found here. Simply remove any spaces from the names, e.g. DeviceLaptop
settings*arrayThe list of additional settings beyond the defaults.
contextarrayA list of data bindings that are provided by the component.
stylesarrayShorthand for adding settings for styling.

Includes: "margin", "padding", "size", "background", "border"
hasChildrenbooleanDetermines if the component can be a container for other components or not.
showSettingsBarbooleanDetermines if the preview settings bar will float above a selected component.
infostringAn optional info message to display at the bottom of the component settings in the builder.

📘

Component schema examples

If you'd like to see some real examples of how components are configured, you can view the component schemas for each of Budibase's core components here.

Settings

The settings array defines which settings are rendered inside the builder for this component. If a settings object contains "section": true then it is expected to be a section with its own array of settings.

Required fields are marked by an asterisk.

PropertyTypeDescription
type*stringThe type of the setting.

A full list of setting types can be found in the componentMap
key*stringA unique identifier for the setting
label*stringThe label to show in the builder for this setting
dependsOnstring | DependsOnSpecifies another setting which this one depends on. This setting will not be shown unless the other setting exists.

If a string value is provided, a single setting key is expected. If an object, setting and value keys are expected, which will check against a specific value.
defaultValueanyThe default value for this setting for newly created components
optionsarrayA list of options for settings of type select
minnumberThe minimum value of the setting
maxnumberThe maximum value of the setting
showInBarbooleanWhether to show this setting in the preview settings bar, if enabled for this component
barStyleBarStyleThe style of bar component to show for this setting
placeholderstringThe placeholder value to be passed to the rendered settings component
sectionbooleanIndicates if a settings section is being defined

Sections cannot be nested within another section
name
[section only]
stringThe name of the section

Depends on

If a string value is provided, then the setting will only show if the specified field is present, i.e. not null, undefined, empty, false or 0.

Alternatively an object can be provided with the following properties. Required fields marked by an asterisk.

KeyTypeDescription
setting*stringThe name of the setting to depend on
value*anyThe value the 'depends on' setting must be for this setting to present
invertbooleanIf true, the 'depends on' setting must NOT match the specified value

Select options

If a setting is of type select, then an options array must also be specified to control which options are available for the setting. The options passed in must have the following structure:

KeyTypeDescription
labelstringThe readable label shown for this option
valueanyThe option value
barIconstringIf showing this setting in the settings bar and using a bar type of buttons, this key defines which spectrum icon to render in the bar

A full list of the available icons can be found here. Simply remove any spaces from the names, e.g. DeviceLaptop
barTitlestringIf showing this setting in the settings bar and using a bar type of buttons, this key defines the title text to be shown when hovering over the icon

Enumerations

A general table of the enumerated values that can be used throughout the component schema. Each enumeration value is comma separated and case sensitive.

NameValues
BarStylebuttons, picker