Widget Configuration

Exposing configuration lets anyone who adds your widget in the No-Code Builder customize it without editing code. You define the fields once in the Widget Registry; they become a form in the No-Code Builder, and your widget reads the chosen values at runtime via sdk.getProps().

How It Works

1. You add a configuration object (with a properties array) and defaultConfig to your widget definition in extensions_registry.json.
2. When someone adds or edits the widget on a page, the No-Code Builder shows a form built from those properties.
3. When the widget runs, the SDK makes the current configuration values available via sdk.getProps().
4. If configuration changes while the widget is active, the SDK emits a propsChanged event so your widget can react.

What You Need in the Registry

Add a configuration object with a properties array. Each property has at least name, label, and type; you can add description, defaultValue, rules, and for type: "select" an options array. Add a defaultConfig object that maps each property name to a default value. Set settings.configurable to true so the configuration form is shown.

Minimal Example

"configuration": {
  "properties": [
    {
      "name": "cards_per_row",
      "type": "number",
      "label": "Cards Per Row",
      "defaultValue": 3,
      "rules": { "required": true, "minimum": 1, "maximum": 6 }
    }
  ]
},
"defaultConfig": {
  "cards_per_row": 3
},
"settings": {
  "configurable": true
}

Configuration Object

Field	Type	Required	Description
properties	array	Yes	Array of field objects (see Config Field below).

Config Field

Each item in properties defines one form field:

Field	Type	Required	Description
name	string	Yes	Unique key for this property; use this name as the key in getProps().
label	string	Yes	Label shown in the No-Code Builder form.
type	string	Yes	Field type (see Field Types table below).
description	string	No	Help text shown below the label.
defaultValue	any	No	Default value for the field.
rules	object	No	Validation rules (see Field Rules table below).
options	array	No	For type: "select" only; array of { "value": "...", "label": "..." } (see Select Option below).

Field Types

Type	Description
text	Single-line text input.
number	Numeric input. Use rules.minimum and rules.maximum for bounds.
color	Color picker (e.g. hex values).
date	Date input.
boolean	True/false toggle or choice.
select	Dropdown; provide options array with value and label for each choice.

Field Rules

Use the rules object to validate input:

Rule	Type	Description
required	boolean	If true, the field must have a value.
minLength	integer	Minimum string length (for text).
maxLength	integer	Maximum string length (for text).
pattern	string	Regex pattern for text validation.
minimum	number	Minimum value (for number).
maximum	number	Maximum value (for number).

Select Option

For type: "select", each option in the options array must have:

Field	Type	Required	Description
value	string	Yes	Value stored and returned by getProps().
label	string	Yes	Label shown in the dropdown.

defaultConfig

The defaultConfig object maps each property name to a default value. Keys must match the name of items in configuration.properties. These values are used when the widget is first added or when a value is not set by the editor.

Example:

"configuration": {
  "properties": [
    {
      "name": "cards_per_row",
      "type": "number",
      "label": "Cards Per Row",
      "defaultValue": 3,
      "rules": { "required": true, "minimum": 1, "maximum": 6 }
    },
    {
      "name": "card_style",
      "type": "select",
      "label": "Card Style",
      "defaultValue": "shadow",
      "options": [
        { "value": "flat", "label": "Flat" },
        { "value": "shadow", "label": "Shadow" },
        { "value": "bordered", "label": "Bordered" }
      ]
    }
  ]
},
"defaultConfig": {
  "cards_per_row": 3,
  "card_style": "shadow"
}

Tip: defaultValue (on each property) and defaultConfig (on the widget) serve similar roles. When both are set for the same property, one value is used as the starting configuration — check your platform's behavior if you use both.

Set settings.configurable to true so the configuration form is shown in the No-Code Builder.

Using Configuration in Your Widget

Call sdk.getProps() to read the current configuration values. Each key in the returned object corresponds to a property name from configuration.properties.

Reading props

export async function init(sdk) {
  await sdk.whenReady()

  const props = sdk.getProps()
  console.log(props.cards_per_row) // 3
}

Reacting to changes

When an editor updates configuration in the No-Code Builder, the SDK emits a propsChanged event. Listen for it to keep your widget in sync:

export async function init(sdk) {
  await sdk.whenReady()

  const props = sdk.getProps()
  render(props)

  sdk.on('propsChanged', (newProps) => {
    render(newProps)
  })
}

Applying props to styles

Use configuration values to set CSS custom properties on your widget, then reference them in your styles:

function applyStyles(sdk, props) {
  const host = sdk.getContainer().host
  host.style.setProperty('--cards-per-row', props.cards_per_row)
  host.style.setProperty('--card-bg', props.card_background)
}

.card-grid {
  display: grid;
  grid-template-columns: repeat(var(--cards-per-row, 3), 1fr);
  gap: 20px;
  background: var(--card-bg, #ffffff);
}

Example

A "Card Grid" widget defines a number (cards_per_row), colors (card_background, card_text_color), and a select (show_icons with options "yes" / "no"). In the registry you add those to configuration.properties and defaultConfig. In your widget code you read them with sdk.getProps() and use the values to build the grid, set colors, and conditionally show icons. When an editor changes "Cards Per Row" to 4 or picks "No" for "Show Icons", the propsChanged event fires and your widget updates.

Troubleshooting

The configuration form does not appear

• Ensure settings.configurable is true for the widget.
• Ensure the widget has a configuration object with a non-empty properties array.

Props are empty or undefined

• Call sdk.getProps() after await sdk.whenReady() — the SDK must be initialized first.
• Ensure the property has a key in defaultConfig so a default is always available.
• Ensure the property names in your code match the name in configuration.properties exactly (case-sensitive).

Next Steps

• Widget Runtime — SDK API reference for getProps() and propsChanged
• Using React — React-specific patterns for reactive props
• Widget Definition Reference — All field types, rules, and configuration structure
• Repository Layout — Organizing your widget repository
• Card Grid widget.json in the template repository — Working example with multiple configuration property types (color pickers, number inputs, selects)