Add a Custom Element Site Widget Extension in the CLI

The Wix CLI makes it easy to add and develop site widgets in your app. These are considered app extensions, and appear on the Extensions page in your app's dashboard.

Custom element site widgets extensions are site widget extensions built in the CLI with custom element technology. The custom element is essentially a new HTML tag that you define, which is made available in the Wix editors as a widget.

The Wix CLI creates the necessary files with template code so you can easily start developing your site widget. It also calls define() for the custom element that the site widget is built on, so you don't need to explicitly call it in your code.

Follow the instructions below to:

1. Add a custom element site widget to your app.
2. Test the site widget on a site.
3. Deploy your app with the site widget.

Before you begin

• You must have an app project that was created using the Wix CLI.
• You must be logged into your Wix Studio account. If you don’t already have one, sign up for a Wix Studio account.

Step 1 | Add a site widget to your app

In the terminal:

1. Navigate to your project repo.

2. Run the following command:

   Copy

   The CLI will display a menu of extensions to generate. Select Site Widget and hit enter, then select Custom Element and hit enter. The CLI will then prompt you for the following items:

   • Element folder: The name of the folder in the project repo that contains the custom element code that the site widget is built on. Only you will see this.
   • Element name: The name of the element that appears in the element.json configuration file. Only you will see this.

Upon completion, the extension files will be created in your project directory with the following structure:

• thumbnail.png - This file is optional and is the thumbnail displayed in the Add Panel for your site widget. Without a thumbnail, your widget will not appear in the Add Panel.
• element.json - This file is required and configures how your site widget integrates with a Wix site. For example, it sets the widget's width and height on the site. It is generated with default settings that can be edited later.
• element.tsx - This file is required and contains the custom element code that supports the site widget.
• panel.tsx - This file is required and contains the code for the site widget settings panel.

Step 2 | Testing your site widget

You can test your site widget while you're developing by running the following command:

Select the option in the CLI menu to view your site widget in the editor. This will open your test site editor, where you can view and try out your site widget.

Why do I get a placeholder when previewing my site widget?

In some cases, your site widget does not display when previewed, but does display as expected when viewed on a published site. We are currently working to fix this issue, but in the meantime, we display a placeholder.

This can happen if:

• You open the dashboard, site, or editor from the menu options. Run npm run dev to restart your local environment.
• You preview a site when the site was opened with the editor menu option. Run build and then release to release a new version.

Step 3 | Build and deploy your app

Once your app is ready for production, you can build it and release a version in the app dashboard.

1. Run the following command to build your app:

   Copy

2. Run the following command and follow the prompts to release an app version:

   Copy

An app version allows you to publish an app to the Wix App Market or install it on a site with a direct install URL. You can view your app versions in the app dashboard.

For more information about building and deploying your app, see Build and Deploy an App with the CLI.

Delete a site widget extension

To delete an existing site widget extension from your app, delete the subfolder under src/site/plugins/custom-element/ that contains your site plugin's files.

See also

• Tutorial | Create an App with Wix CLI
• Tutorial | Build a Locations App Using the Wix CLI