Add Self-hosted Site Plugin Extensions with Custom Elements

A site plugin is a type of component that site builders can place in designated locations (called slots) within Wix apps. Site plugins extend the functionality of their host app by providing additional UI elements and business logic.

You can create a site plugin 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 editor as a plugin.

To create this extension, do the following:

• Code and deploy the custom element.
• Optionally, code and deploy your widget's settings panel.
• In the app dashboard in Wix Studio, set up the plugin and configure additional extensions, authentication, permissions, and more.
  Learn more about setting up your app in the app dashboard

You can create a new app for your site plugin or add it to an existing app.

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.

Connect to the plugin's API

To enable plugins to communicate with their hosts, each slot supports an API that provides data about the plugin's context (for example, a plugin for the product page can access the productId property, which the host widget sets to indicate the item that it’s currently displaying).

Learn more about the plugin APIs supported on each app page.

When building a plugin using a custom element, the properties provided in the plugin API are added to the custom elements as attributes. You can get their values in your code using the attributeChangedCallback() function, for example:

Integrate with Wix APIs

Plugins can use Wix APIs to interact with Wix’s business solutions, such as eCommerce, Stores, and Bookings. Learn more about integrating with Wix APIs

Step 2 | Code your plugin's settings panel

Your plugin should have a settings panel in the editor, which is displayed when a user clicks the Settings button in the plugin'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 plugin, use the Widget API’s setProp() function. The 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 plugin 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 | Build your app's dashboard page

If your plugin requires a back office management interface, you can create one either within the Wix dashboard, or as an external dashboard on a third-party platform. Learn how to build a dashboard page to manage your site plugin

Step 4 | Set up the plugin in your app dashboard

To make your plugin available for installation on sites, set up the plugin in your app dashboard and configure its installation settings and market listing. Your plugin's market listing determines how it will appear to users in the plugin explorer in the editors, including the plugin's name, icon, and teaser.

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 find the Site Plugin extension.
4. Click + Create and then select Custom Element
5. Configure your plugin's basic data:
   • Plugin name: The plugin name that is displayed to users.
   • 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.
6. Configure how your plugin can be added to sites:
   • Which Wix app does it extend?: The Wix app for which you're building the plugin.
   • Slots this plugin can be added to: Select one or more slots that are appropriate for your plugin. Select slots in order of priority. If none of the selected slots are available, users can choose to replace a plugin that’s already been added.
   • Add this plugin automatically to the site: Whether the plugin is automatically added to a slot when a user installs your app. If you set your plugin to be automatically added to a slot on installation, it will be placed in the first available slot according to the order you defined. If that slot is occupied, it will be added in the next available slot, and so on. If there are no available slots, it will not be added.
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. Configure your plugin's market listing:
   • Teaser: A short promotional description for your plugin's market listing.
   • Icon: An icon for your plugin's market listing. Upload a square JPG or PNG file.
9. Click Save.
10. If your app is already approved and published, publish a new version in the app dashboard.

Step 5 | Test and preview

Your unpublished plugins are available for installation in the editors when you're logged in with your developer account. This makes it easy to preview and test your plugin in a real environment.

To test your plugin in the editor:

1. Create a site and install the Wix app that your plugin extends.
2. Go to the page on which you want to install your plugin, and click the host widget's Plugin icon.
   Your unpublished plugins will appear in the plugin explorer.
3. Hover over your plugin, and then click Add.
   When prompted for consent, select the checkbox and click Agree & Add.

Once you install your plugin on a site, you can preview or publish the site to test the plugin's functionality and make sure it's working properly.

Step 6 | Submit and publish your plugin

When you’ve finished building and testing your plugin, you’re ready to launch and monetize your app.

Learn more about submitting your app for review.