Wix Blocks: Using Custom Elements

Enhance your Blocks widgets with your own design features and CSS capabilities, use any web technology or third party libraries, with Custom Elements. You can add any Javascript component by linking a custom element to a server URL or a Velo file. If needed, you can set more attributes directly from Blocks.

What Are Custom Elements

Custom elements let you use your own HTML tags in Blocks widgets. These elements work across all supported browsers, and can be used with any JavaScript ES6 library or framework that works with HTML 5.

With custom elements, you can:

• Design elements with additional functionality or CSS capabilities.
• Embed any widget that requires full DOM access.

Code requirements:

• Your code must be up to date and HTML5 compatible. You should transpile your JS to ES2020.
• If you are hosting your own code, it must be hosted over a secure protocol (HTTPS). Also, all HTTP calls from the code needs to be to HTTPS endpoints.
• If you are hosting your own code, all relevant design settings and complex functionalities (for example the CSS and other JS files), must be bundled in a single JS file. Don’t set anything in a separate file.

Step 1 | Adding and Setting Up a Custom Element

Add as many custom elements as you need to your widget. After dragging a custom element to your widget, define its source (server URL or a Velo file) and give it a tag name to appear in the page registry. The tag name should be the exact name used in the customElement.define() function.

Step 2 | Adjust the Custom Element by Setting Attributes

The custom element HTML attributes let you adjust your element according to parameters that you control. For example, you can set dynamic texts or change colors on the go, or change the custom element inner logic according to the widget’s instance on a specific site (using getDecodedAppInstance()).

There are two ways to initiate your custom element's attributes in the Blocks app:

A. Click Set Attributes: Set and initiate your element’s attributes by adding them to this designated panel. You can also edit or remove the attributes later.

1. Click Set Attributes on the custom element.
2. Click New Attribute.
3. Enter a name for the attribute, for example, title.
4. Enter the value for the attribute (it can be any relevant string).

B. Use Code: Set your element’s attributes in the widget code with the setAttribute() function.

For example, let's say that you need to use data from your widget's instance on a specific site, inside your the custom element’s logic. This data is returned by the getDecodedAppInstance() function. Your widget code will look like this:

1
import wixApplication from 'wix-application';
2

3
$w.onReady(function () {
4
const instance = await wixApplication.getDecodedAppInstance();
5
$w('#myCustomElement').setAttribute('instanceIdAttribute', instance.instanceId);
6
});

Step 3 | Connect the Custom Element to Your Widget's Functionality

In most cases, you’ll want to use the custom element logic from one or more of these:

• The widget’s panel
• The site where the app is installed
• Another widget in the app

To do this, define properties in the widget API. These properties should represent the Custom Element attributes. The following steps explain how.

Add a property to the widget API

1. Click the Widget API icon on the bottom of your Blocks screen.
2. Click Add New Property or hover over Properties and click the icon.
3. Name your property, select its type and default values, add a description.
4. Click Create.

Set the attribute in the onPropsChanged() and onReady() functions

Define your widget's onPropsChanged() function and onReady() functions to handle a change in this property. For example, let's say we added a property named title, which enables the user to change the title of the custom element. The code below sets the custom element attribute title to be the same as the widget's property title. Creating a function to apply props and using it in both the onPropsChange() and onReady() events, helps you avoid problems when your props aren't applied in preview mode, or other similar situations.

1
$widget.onPropsChanged((oldProps, newProps) => {
2
    applyProps(newProps)
3
});
4

5
$w.onReady(function () {
6
	applyProps($widget.props)
7
});
8

9
function applyProps(props) {
10
    $w('#customElement1').setAttribute('title', props.title);
11
}

Optional: create a panel to change the property

Create a panel that allows a site creator who installed your app to be able to change the widget properties (and therefore, the custom element attributes).

1. Click the Panels tab at the top of Blocks.
2. Click Create New Panel, or open a panel that you already created.
3. Add an element that can receive a the new property (in our example, it's an input element named 'panelTextInput1').
4. Open the designated code area in the Panels tab.
5. Add code that will pass the property from the panel to the widget (in our example, it goes both ways):

1
import wixWidget from 'wix-widget'; 
2

3
$w.onReady(async function () {
4
   const props = await wixWidget.getProps();
5
    $w('#panelTextInput1').value = props.title;
6
    $w('#panelTextInput1').onChange(async () => {
7
        wixWidget.setProps({ title: $w('#panelTextInput1').value });
8
    })
9
});

To summarize this last step: the site-creator changed the title through the panel. The new title was passed to the widget through the title property. When the property changed, the new title was sent to the custom element as an attribute.

Optional: Use the Color Intput panel element

You can also use the Color Input element (in our case its name is panelColorPicker1) to set some style properties. For example:

1
$w('#panelColorPicker1').onColorChange(async () => {
2
       wixWidget.setProps({ background_color: $w('#panelColorPicker1').color });
3
   })