Widget Definition Reference

This page documents every field of a widget entry in the widgets array of extensions_registry.json. For the root of the registry file, see Registry Reference.

Working example

The template repository contains a complete extensions_registry.json with example widgets, a global script, and a stylesheet — a useful reference alongside this documentation.

Widget Object

Field	Type	Required	Default	Description
title	string	Yes	—	Display name shown to users
type	string	Yes	—	Unique widget identifier — must be unique across your community
category	string	Yes	—	Free-form category label, e.g. "engagement", "analytics"
content	object	Conditional	—	External hosting — see Content Object. Required if source is not set.
source	object	Conditional	—	Repository hosting — see Source Block. Required if content is not set.
version	string	No	"1.0.0"	Widget version following semver
description	string	No	""	Brief description of the widget
containers	array of strings	No	["Full width"]	Page zones where the widget can be placed. Values: "Full width", "Left container", "Sidebar"
widgetsLibrary	boolean	No	true	When true, the widget appears in the No-Code Builder library
imageName	string	No	"banner"	Built-in thumbnail identifier — see Thumbnails. Ignored when imageSrc is set.
imageSrc	string	No	—	Custom thumbnail — absolute URL or relative repository path. See Thumbnails. Mutually exclusive with imageName.
settings	object	No	shared false, container false, others true	Widget behavior settings — see Settings Object
configuration	object	No	—	Form fields for the No-Code Builder — see Configuration Object
defaultConfig	object	No	—	Default values for configuration properties

XOR Requirement: Each widget must have exactly one of content or source — never both, never neither.

Important: The type field is the widget's unique identifier. Use a descriptive, namespaced format like mycompany_welcome_banner to avoid conflicts with other widgets.

Settings Object

Field	Type	Required	Default	Description
configurable	boolean	No	true	Whether users can configure the widget after adding it
editable	boolean	No	true	Whether the widget content can be edited
removable	boolean	No	true	Whether users can remove the widget from pages
shared	boolean	No	false	When true, one widget instance is shared across every page it appears on — edits propagate everywhere. Opt in explicitly; the default keeps the widget local to each page.
movable	boolean	No	true	Whether users can reposition the widget
container	boolean	No	false	Whether the widget acts as a container for other widgets

An empty settings: {} object is valid — all fields take their defaults.

Content Object

Field	Type	Required	Default	Description
endpoint	string	Yes	—	Public URL to widget content, must start with https://
method	string	No	"GET"	HTTP method — "GET" or "POST"
cacheStrategy	string	No	—	Caching behavior — "none", "no-cache", "ttl", or "permanent"
cacheTtlSeconds	integer	No	—	Cache duration in seconds — use with cacheStrategy: "ttl"
requiresAuthentication	boolean	No	false	Not supported — leave false or omit
headers	object	No	—	Optional headers sent with the request
body	object	No	—	Optional request body, for POST
params	object	No	—	Optional query parameters

Source Block

Field	Type	Required	Default	Description
path	string	Yes	—	Directory path relative to repository root
entry	string	Yes	—	HTML entry point file relative to path

Configuration Object

Field	Type	Required	Default	Description
properties	array of objects	Yes	—	Form fields — see ConfigField Object

ConfigField Object

Field	Type	Required	Default	Description
name	string	Yes	—	Field identifier, used as the configuration key
label	string	Yes	—	Field label shown in the No-Code Builder
type	string	Yes	—	Field type — "text", "number", "color", "date", "boolean", or "select"
description	string	No	—	Help text shown under the field
defaultValue	any	No	—	Pre-filled value
rules	object	No	—	Validation rules — see FieldRules Object
options	array	No	—	Only for "select" type — see SelectOption Object

FieldRules Object

Field	Type	Required	Default	Description
required	boolean	No	—	Whether the field must be filled in
minLength	integer	No	—	Minimum string length
maxLength	integer	No	—	Maximum string length
pattern	string	No	—	Regex the value must match
minimum	number	No	—	Minimum numeric value
maximum	number	No	—	Maximum numeric value

SelectOption Object

Field	Type	Required	Default	Description
value	string	Yes	—	Value stored when the option is selected
label	string	Yes	—	Label shown in the dropdown

Thumbnails

A thumbnail is the preview image shown for a widget in the No-Code Builder library. You have three ways to set one, controlled by two fields on the widget object:

• Built-in — set imageName to one of the built-in identifiers.
• External URL — set imageSrc to a publicly accessible image URL.
• Repository-hosted — set imageSrc to a relative path to an image file in your repository.

imageName and imageSrc are mutually exclusive — if both are set, imageSrc wins. If neither is set, the default imageName: "banner" applies.

Custom thumbnails (external or repository-hosted) must be 512 KB or smaller. For best display, use 420×145 pixels — dimensions are not enforced.

Built-in (imageName)

Set imageName to one of the identifiers below. Each preview shows the thumbnail at a reduced size.

imageName	Preview
announcement_card
autopilot
autopilot_theloops
badges
banner
categories
community_statistics
container-2.1
create_idea
customer_education_widget
dynamic_content
events_calendar
featured_topics
groups
hero_banner
html_widget
ideation_pipeline
introduction_bar
leaderboard
most_liked
quicklinks
recommendations
solved_topics
statistics
tabs
tag_cloud

Example: "imageName": "banner" uses the built-in banner thumbnail.

External URL (imageSrc)

Point to any publicly accessible HTTPS image:

"imageSrc": "https://example.com/images/my-widget-preview.png"

Repository-hosted (imageSrc)

Store the image in your repository and reference it with a relative path from the repo root:

"imageSrc": "./images/preview.png"

Both ./images/preview.png and images/preview.png are valid. During publishing, the platform fetches the image from your repository, publishes it, and rewrites the path to an absolute URL. The resulting registry always contains absolute URLs.

Path rules:

• No path traversal (../ is not allowed)
• No absolute paths (must not start with /)
• The image must exist in the repository at the referenced path

Validation Rules

The schema enforces these rules:

1. Root object must have a widgets property (required)
2. widgets must be an array (may be empty)
3. Each widget must include all required fields
4. attributes on scripts and stylesheets must be an object with string values

Validation errors

For a full list of validation and build errors, including causes and fixes, see Error Codes.

Best Practices

1. Use globally unique type values: The type is the widget ID and must be unique across your entire community. Use a prefix like your company or project name (e.g., acme_welcome_banner)
2. Keep descriptions concise: Brief but descriptive
3. Set widgetsLibrary: true to make widgets appear in the No-Code Builder library
4. Use semantic versioning: Follow semver (major.minor.patch)
5. Validate before pushing: Use a JSON validator to catch syntax errors

Next Steps

• Hosting Widgets — how to choose between external and repository hosting
• Widget Configuration — how to add form fields for the No-Code Builder
• Registry Reference — the root of extensions_registry.json
• Script Definition Reference — global script entries
• Stylesheet Definition Reference — global stylesheet entries
• Error Codes — reference for validation failures