Site Widget Extension Files and Code

Add a new custom element site widget to your CLI project with the generate command and selecting Site Widget.

The CLI generates this directory structure in your project repo:

In the site widget folder, the following files are created:

• An element.extension.ts file that defines a builder containing the site configuration settings of your site widget.
• An element.tsx file that contains the main code for the custom element that the site widget is built on.
• A element.panel.tsx file that contains the code for your widget's settings panel.
• A element.module.css file that configures CSS styling to customize your plugin's appearance. It's generated with some initial styles to help you get started.
• An default thumbnail.png file that contains the thumbnail displayed in the Add Elements panel for your site widget. This file is optional, but without a thumbnail, your widget won't appear in the Add Elements panel.

It's possible to create each of these files yourself, but we don't recommend it for a couple of reasons:

• You're more likely to make errors in the filepath if you add the files and folders yourself. If the filepath is incorrect, the CLI can't detect the custom element and the site widget won't work.
• The auto-generated files offer React template code that helps you get started developing.

element.extension.ts

The element.extension.ts file configures the settings for how your site widget appears on a user's site. This file is required, so don't delete it after the site widget is generated. If you add your own files, you must include element.extension.ts.

When you generate a new site widget in your project, you'll see the following code in element.extension.ts:

You can edit the configuration object and add properties as follows:

element.tsx

The element.tsx file is where you write the code for the custom element that defines the site widget. You can write code in other files and include it here, but you must return your main component in this file. This is where the CLI will look for the site widget definition.

This file is required for the site widget to work, so don't delete it. If you add the files on your own, you must include element.tsx.

When the element.tsx file is generated, it looks like this:

The file sets up a React component called CustomElement, where you write the custom element code. It also calls reactToWebComponent to convert your React component to a custom element, and exports the custom element so Wix can work with it as a site widget.

We recommend writing your code in React, since the rest of the CLI also works with React. However, you can also write code directly in element.tsx with JavaScript. If you do so, make sure to export the custom element, like in the example below:

Note that you don't need to call define() even here; Wix still takes care of that for you even if you haven't defined the custom element in React.

element.panel.tsx

The element.panel.tsx file contains the code defining your site widget's settings panel. The settings panel lets site users customize the widget after they install your app.

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're reflected in your widget in the editor, use the attributeChangedCallback() in your custom element's code.

After the site widget is generated, you'll see code like this in element.panel.tsx file:

The file contains a React component called Panel that defines the site widget's settings panel with the following key features:

1. State Management: Uses React hooks (useState, useEffect, useCallback) to manage the display name property.
2. Widget Integration: Uses the widget API from @wix/editor to get and set widget properties.
3. UI Components: Utilizes Wix Design System components like SidePanel, Input, and FormField for a consistent user interface.

As with element.tsx, you can write code in other files and include it here, but you must return your main component in this file. The panel code must be written in React to work with the rest of the CLI.

Learn more about creating a settings panel for a site widget built with the CLI.

Widget thumbnail

To display a thumbnail for your site widget in the Add Elements panel, you need to add a presets configuration to your element.extension.ts file and create a public folder with your thumbnail image.

Add the presets configuration to your element.extension.ts file after the settings property:

Create a public folder at the root level of your project and add your thumbnail image file.