About Site Widget Extensions

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.

When working in the site editor, site owners can adjust the size of the widget, reposition it, and customize it using its settings panel.

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

Essential widgets

When configuring a site widget, you can set it to be essential, meaning that it is crucial to your app’s functionality. Deleting an essential widget (or the section or page that contain it) from a site, will also delete the entire app. An essential widget can only be added once to a site and users cannot duplicate it.

Implementation options

You can add a site widget extension using:

• Wix Blocks: Create a site widget in Wix's native app editor. Design your widget using visual layout and design tools, and code your business logic using Velo, Wix’s native coding solution.
• Wix CLI: Create a widget using the CLI, with your code by default deployed on our servers. The creation and setup process of your widget takes place in the terminal. Then, to edit your widget, you write code directly in your CLI app project's files.
• Self-hosted custom element: Create a site widget 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 editors as a widget.

Choosing your implementation

Here are some factors to consider when choosing which implementation to work with:

• Site widgets currently can't be pinned to a specific location on a page. If your app requires this, best to use an embedded script component.
• Site widgets built with Wix Blocks support all the functionality available in Wix's editor elements. If your extension should include functionality that isn't supported, use the Wix CLI or a self-hosted custom element.
• Site widgets built with Wix Blocks can connect to a site's color and typography themes, and support advanced capabilities for configuring the widget customization experience in the editor.

Interact with a user site

The way to interact with a user site from your site widget extension depends on your implementation. For widgets created with Blocks, use Velo. For widgets created via the CLI, use the Site API.

Sandboxing in the editor

When rendered in the editor, custom elements are sandboxed to enhance security. This means they're treated as if they come from a different domain, and Wix does not support the allow-same-origin directive in the sandbox attribute. As a result, your site widget can't access same-origin resources in the editor.

This restriction impacts several key web storage and caching APIs:

• Cookie Store API, such as document.cookie
• Web Storage API, such as Window.localStorage and Window.sessionStorage
• IndexedDB API
• Cache API

To overcome these limitations:

1. Detect the environment with viewMode().
2. When in the editor, mock the storage or modify your API usage accordingly.