> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Site Widget Extension Files and Code

## Article: Site Widget Extension Files and Code

## Article Link: https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/site-extensions/custom-element-site-widgets/site-widget-extension-files-and-code.md

## Article Content:

# Files and Code for Custom Element Site Widget Extensions

<blockquote classname="note">

**CLI Documentation Notice**

We've released a [new Wix CLI](https://dev.wix.com/docs/wix-cli/guides/about-the-wix-cli.md). Continue here if your project uses the Wix CLI for Apps. [Determine which CLI your project uses](https://dev.wix.com/docs/wix-cli/guides/development/determine-which-cli-your-project-uses.md). 

</blockquote>

[Add a new custom element site widget](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/site-extensions/custom-element-site-widgets/add-a-site-widget-extension-in-the-cli.md) to your CLI project with the following command:

```bash
npm run generate -- --type=SITE_WIDGET
```

The CLI generates this directory structure in your project repo:

```tsx
.
└── <your-app-name>/
    └── src/
        ├── assets/
        │   └── <your-widget-name>/
        │       └── thumbnail.png
        └── site/
            └── widgets/
                └── custom-elements/
                    └── <your-widget-name>/
                        ├── element.json
                        ├── element.tsx
                        └── panel.tsx
```

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

+ An `element.json` file that defines 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 `panel.tsx` file that contains the code for your widget's settings panel.
+ 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 will not appear in the Add Elements panel.

![Site widget in add elements panel](https://wixmp-833713b177cebf373f611808.wixmp.com/images/e15fcc86fa5386a46cbe05568ab578b1.png)

It is 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.json**

The `element.json` file configures the settings for how your site widget appears 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.json`.

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

```json
{
  "$schema": "https://dev.wix.com/wix-cli/schemas/custom-element.json",
  "id": "d1ec650c-8a06-446c-87ce-1343a04e6bfe",
  "name": "Custom Element",
  "width": {
    "defaultWidth": 300,
    "allowStretch": true
  },
  "height": {
    "defaultHeight": 150
  },
  "installation": {
    "autoAddToSite": true,
    "essential": false
  },
  "presets": [{
    "id": "0c28afa4-6582-4f2e-8daf-f8ddfadddf07",
    "thumbnailUrl": "../../../../assets/<your-custom-element-name>/thumbnail.png",
  }]
}
```

You can edit the JSON and add keys as follows:

| Key                            | Type     | Description                                                                                                                                                                                                                                                                                                                                |
|----------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`                             | string   | A unique identifier for your site widget. The CLI generates this GUID for you. If you add the JSON file yourself, you must generate your own GUID.                                                                                                                                                                                          |
| `name`                           | string   | The name of the site widget as it appears in the [app dashboard](https://manage.wix.com/account/custom-apps). The CLI prompts you for the name when you create the site widget.                                                                                                                                                                              |
| `height.defaultHeight`           | number   | The widget's height in pixels when it is first installed on a site.                                                                                                                                                                                                                                                                    |
| `width.defaultWidth`             | number   | The widget's width in pixels when it is first installed on a site.                                                                                                                                                                                                                                                                     |
| `width.stretchByDefault`         | boolean  | Whether to stretch the widget to full width on installation.                                                                                                                                                                                                                 |
| `width.allowStretch`             | boolean  | Whether to allow users to toggle the widget between full-width and default width.                                                                                                                                                                                                                                   |
| `installation.autoAddToSite`     | boolean  | Whether to automatically add the widget to the site home page upon installation.  Users can later move these widgets around on their site.                                                                                                                                                                                                                                                                      |
| `installation.essential`         | boolean  | Whether to mark the widget as a core part of your app's functionality. You can set this key to `true` only if the widget is added as part of a [site page extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/site-extensions/site-pages/about-site-page-extensions.md). If set to `true`, deleting this widget (or the section or page that contain it) from a site will also delete the app.                                                                                                                                                                                                |
| `presets[0].id `        | string  | A unique identifier for the preset object containing your thumbnail. This is a randomly generated GUID.  |
| `presets[0].thumbnailUrl`        | string  |  Either a relative path to a thumbnail file (for example, `../../../../assets/my-widget/thumbnail.png`) or an absolute URL (for example, `https://mysite.com/myimage.png`).  |

## **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:

```javascript
import React, { type FC } from 'react';
import ReactDOM from 'react-dom';
import reactToWebComponent from 'react-to-webcomponent';
import styles from './element.module.css';

interface Props {
  displayName?: string;
}

const CustomElement: FC<Props> = ({
  displayName = `Your Widget's Title`,
}) => {
  return (
    <div className={styles.root}>
      <h2>{displayName}</h2>
      <hr />
      <p>
        This is a Site Widget generated by Wix CLI.<br />
        Continue to develop this widget at <code>'src/site/widgets/custom-elements/your-widget-filename'</code>.
      </p>
    </div>
  );
};

const customElement = reactToWebComponent(
  CustomElement,
  React,
  ReactDOM as any,
  {
    props: {
      displayName: 'string',
    },
  }
);

export default customElement;
```

The file sets up a React component called `CustomElement`, where you write the custom element code. It also calls [`reactToWebComponent`](https://www.npmjs.com/package/react-to-webcomponent) 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:

```javascript
class CustomElement extends HTMLElement {
  constructor() {
    super();
  }
  // Element functionality written in here
}

export default CustomElement;
```

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.

## **panel.tsx**

The `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](https://dev.wix.com/docs/sdk.md) to [access widget properties](https://dev.wix.com/docs/sdk/host-modules/editor/widget/introduction.md) and [retrieve environmental data from the editor](https://dev.wix.com/docs/sdk/host-modules/editor/info/introduction.md), 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()`](https://dev.wix.com/docs/sdk/host-modules/editor/widget/set-prop.md) 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()`](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#responding_to_attribute_changes) in your custom element's code.

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

```javascript
import React from 'react';
import { editor } from '@wix/editor';
import { WixDesignSystemProvider } from '@wix/design-system';
import { WixProvider } from '@wix/sdk-react';

export function withProviders<TProps extends object>(
  Component: React.ComponentType<TProps>
) {
  return function EditorProviders(props: TProps) {
    return (
      <WixDesignSystemProvider>
        <WixProvider host={editor.host()} auth={editor.auth()}>
          <Component {...props} />
        </WixProvider>
      </WixDesignSystemProvider>
    );
  };
}

const SettingsPanel = () => {
  return (
    <div className={s.panelWrapper}>
    </div>
  );
};

export default withProviders(SettingsPanel);
```

The file contains two important pieces of code:

1. A React component called `SettingsPanel` where you write your code defining the site widget's settings panel.
2. A function `withProviders()` that wraps the component with the necessary React providers. This includes the `<WixDesignSystemProvider>` and `<WixProvider>`.

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](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/site-extensions/site-widgets/create-a-settings-panel-for-a-site-widget-or-plugin-wix-cli-and-self-hosting.md).

## Widget thumbnail

A default `thumbnail.png` file is created in a subdirectory with your widget's name inside your app's `/assets` folder when you generate this extension. The file contains the thumbnail displayed in the Add Elements panel for your site widget. The file isn't required. However, without a thumbnail your widget will not appear in the Add Elements panel.
The file is referenced in the `presets[0].thumbnailUrl` field in the `element.json` file. 

<blockquote class="important">

__Important:__
If you rename the thumbnail file, you must update the path in `presets[0].thumbnailUrl`. If you remove the file, you must remove the object containing your thumbnail from the `presets`  array.

</blockquote>