A custom element site widget in a Wix CLI app is a custom HTML element plus a settings panel.
Note: A Studio Two site doesn't use this extension. Headless projects don't support it. See About Custom Element Site Widgets.
When you add the extension, the generated files land under src/extensions/site/widgets/<widget-folder>/. Generate also adds a default thumbnail at public/thumb.png, and registers the extension in your project's extensions.ts.
| File | What it's for |
|---|---|
<widget-folder>.extension.ts | The configuration file for the widget ID, size, installation, tag name, and file paths. |
<widget-folder>.tsx | The element. This file exports the custom element. |
<widget-folder>.panel.tsx | The settings panel that opens from the widget's action bar in the editor. |
<widget-folder>.module.css | CSS Module styles for the element. |
public/thumb.png | The default thumbnail for the Add panel and the Manage Apps page. The generated presets entry points at this file. |
The CLI calls define() for the custom element. The element file exports the class or the converted React component. It doesn't call define() itself.
The <widget-folder>.extension.ts file declares the widget with extensions.customElement().
Keep this file. If you add the extension yourself, include it.
| Field | Type | Description |
|---|---|---|
id | string | Widget ID as a GUID. It must be unique across extensions in the project. Generate sets it. |
name | string | Display name in the app dashboard. |
width.defaultWidth | number | Width in pixels when the widget is first added to a site. |
width.allowStretch | boolean | Whether the Wix user can toggle the widget between full width and the default width. |
width.stretchByDefault | boolean | Whether the widget stretches to full width when it is first added. |
height.defaultHeight | number | Height in pixels when the widget is first added to a site. |
installation.staticContainer | string | Where the widget is added when the app is installed. "HOMEPAGE" adds it to the site home page. Omit the field and the widget is not added on install. Wix users then add it from the Add panel. In the CLI, automatic installation applies only to the home page. installation.autoAdd is deprecated. Use installation.staticContainer. |
installation.essential | boolean | Whether the widget is essential to the app. Set this only when the widget is part of a site page. An essential widget can be added once, and deleting it removes the app from the site. |
tagName | string | Custom element tag name. Use lowercase, start with a letter, and include at least one hyphen, such as my-element. The CLI registers this tag. |
element | string | Path to the element file, relative to the project's src/ directory. |
settings | string | Path to the settings panel file, relative to the project's src/ directory. |
behaviors.dashboard.dashboardPageComponentId | string | ID of a dashboard page extension. When set, the widget's action bar includes a Manage button that opens that page. |
presets | array | Thumbnail shown in the Add panel and on the Manage Apps page. Each entry has an id GUID, a name, and a thumbnailUrl. |
Generate creates public/thumb.png and sets presets[0].thumbnailUrl to {{BASE_URL}}/public/thumb.png. {{BASE_URL}} resolves to the project's public/ folder.
Replace public/thumb.png with your own image, or add another file under public/ and point thumbnailUrl at it. If you rename the image, update thumbnailUrl. Without a thumbnail, the widget doesn't appear in the Add panel or on the Manage Apps page. See Display a Custom Element Site Widget in the Add Elements Panel in Build Apps.
The <widget-folder>.tsx file exports the custom element. You can write the UI in other files and compose it here. This file is the one the CLI loads.
The generated file uses React and converts the component with reactToWebComponent(). Each prop in the props option maps to a kebab-case attribute. The settings panel writes that attribute with widget.setProp(), and the component receives the value as the prop.
You can export a class that extends HTMLElement instead. List each attribute the element responds to in observedAttributes, and update the element in attributeChangedCallback(). The browser calls attributeChangedCallback() only for attributes in that list.
In either form, don't call define(). The CLI registers tagName for you.
The <widget-folder>.panel.tsx file is a React component. It runs in the editor when the Wix user opens Settings on the widget's action bar. The panel must be React.
Read and write widget properties with widget from @wix/editor. Properties are bound to the custom element's attributes. widget.setProp('display-name', value) updates the display-name attribute, and the element re-renders from that attribute.
For a React element, add the prop to the component and to the props option, then call widget.setProp() with the kebab-case name. For an HTMLElement class, add the attribute to observedAttributes.
When the panel writes several properties, write them one at a time and confirm each value with widget.getProp() before the next write. For a full panel, see Create a Settings Panel for a Site Widget or Plugin in Build Apps.
A Wix CLI project registers the widget in src/extensions.ts. Generate adds the import and the app().use() call:
When the project already has other extensions, Generate appends another .use() call to the existing chain.
Last updated: 2 November 2026