Add Self-hosted Site Widget Extensions with Custom Elements

You can create a site widget extension using custom element technology, with your code deployed on your own server. The custom element is essentially a new HTML tag that you define, which is made available in the Wix editors as a widget.

To create this extension, you need to do the following:

• Code and deploy the custom element.
• Code and deploy your widget's settings panel.
• Configure the widget in your app dashboard.

Step 1 | Code your custom element

Code your custom element and its functionality in a JavaScript file. Use a class to define the element.

In your code, create a class for the custom element and register the custom element.

Here is a sample code snippet:

Custom elements react to DOM-related events. When you create your custom element, use MDN lifecycle callback functions such as connectedCallback() and attributeChangedCallback().

When your code is ready, deploy your custom element’s JavaScript file on a remote or local server.

Step 2 | Code your widget’s settings panel

Your widget must have a settings panel in the editor, which is displayed when a user clicks the Settings button in the widget’s action bar. The panel is rendered as an iframe, which you can build using any tools you like. When it comes to designing the UI, consider using the Wix Design System. It is a collection of reusable React components that you can use to make your panel appear and feel like a native Wix panel.

In the panel’s code, use Wix's JavaScript SDK to access widget properties and retrieve environmental data from the editor, as well as access and manage Wix business solutions.

To apply changes made in the settings panel to the widget, use the Widget API’s setProp() function. Widget properties are bound to your custom element’s attributes, so any change in the properties automatically updates the corresponding attribute. To handle attribute updates so they are reflected in your widget in the editor, use the attributeChangedCallback() in your custom element's code.

Here is a sample code snippet showing how to update a custom element’s attribute:

When your code is ready, deploy your settings panel’s HTML file on a remote or local server.

Step 3 | Configure the widget in your app dashboard

Configure your widget in your app dashboard so that it can be added to sites.

1. In your Wix Studio workspace, select Custom Apps, and then create a new app or select an existing app.
2. In the left menu, select Extensions.
3. Click Create Extension and select Site Widget (Custom Element).
4. Configure your widget’s basic data:
   • Widget name: The element name displayed in the editor.
   • Tag name: The custom element’s tag name that is used when registering the element. The tag name should be identical to the name you use in the customElements.define() function in your JavaScript file.
   • Script URL: The URL where your custom element’s JavaScript code is deployed.
5. Define how your widget is sized when added to a site:
   • Widget width: Whether users can stretch the widget to full width or modify the widget’s width, and how it is sized on installation.
   • Widget height: Whether the widget’s height is adjusted automatically according to the custom element’s content or can be manually adjusted.
6. Define where your widget is added to a site and how instances of the widget are handled in the editor:
   • Define whether your widget is added automatically to the site and on which page. You can add your widget to the site’s homepage or to one of your app’s pages.
   • If you're adding your widget to one of your app's pages, define whether your widget is set as essential, meaning that it is crucial to your app’s functionality. If set as essential, deleting the widget will also delete the entire app.
7. Configure your widget’s action bar in the editor:
   • Settings action button: Provide the URL where your settings panel’s HTML code is deployed.
   • Manage action button (optional): If your app has a dashboard page, select the page you want to open when a user clicks the Manage button in the widget’s action bar.
8. Click Save.

You can now install your widget on a site.

Step 4 | Test and preview

To test your widget in the editors:

1. Select your app from the Custom Apps page in your Wix Studio workspace.
2. Click Test Your App and select Editor.
3. Select the site on which you want to install your app.
4. When prompted for consent, select the checkbox and click Agree & Add.

Once your widget is added to the site, you can preview or publish the site to test the widget’s functionality.

See also

• Tutorial | Create a Self-Hosted App