Add a 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.

Site widgets are draggable UI components that Wix site owners can add to pages on their website. They enhance a site's functionality by displaying content or enabling site visitors to perform various tasks.

The following example shows the Wix FAQ widget in the site editor:

Site widgets in the CLI are built 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 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 Developer account. If you don’t already have one, sign up for a Wix Developer 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 to continue. 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:

• 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 optional but recommended. It contains the code for the site widget settings panel. It is not required, but we strongly recommend creating a panel to give the user control over the widget settings.

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.

The first time you run this command for a new site widget, you'll be prompted to open the site editor to complete the installation.

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 create-version to create a new version.

Step 3 | Build and deploy your app

Once your app is ready for production, you can build it and create 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 create 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.

Summary

You now have a site widget extension configured in your app.

See also

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