Velo: About Custom Elements

Custom elements let you add custom elements to your site that are not currently available "out of the box" with the editor. Custom elements are available from the Embed Code (Wix Editor) or Embed & Social (Wix Studio) section of the Add Elements menu in the editor.

With Velo, you can enhance the behaviors of custom elements even more than what is possible from the editor. You can also host your custom elements with Wix using Velo.

First you create and code the element and its behavior in a JavaScript file. Then you implement how your site should handle events on the custom element. 

How to Create Custom Elements

Here is an outline of the steps for adding custom elements:

1. Check prerequisites. 
2. Code the custom element.
3. Host the JavaScript file.
4. Add a custom element to your site.
5. For really cool custom elements, use Velo to code additional behaviors, such as  code event handling and more functionality.

Prerequisites

Before you start, check prerequisites to make sure you are set up properly to work with custom elements. Some important prerequisites to look at include:

• Get a domain and remove Wix Ads
• Upload images for the custom element in the editor

Code the Custom Element

Code the custom element and its behavior in a static JavaScript file using the Velo IDE or any other IDE. 

Each JavaScript file corresponds to one custom element's implementation of its design and behaviors. Custom elements are defined using the standard ECMAScript 2015 class syntax.

Some of the behaviors and styles you might consider coding in the custom element include: 

• Variables and styles.
• Functions for animations and other behaviors.
• Events. Creating events is the custom element's way of "communicating" with the Wix site using Velo. Events let Velo know that something has to be handled, and parameters can be sent with the event.

Create a class for the custom element and register the custom element. 

Here is a sample code snippet: 

Important!
Keep track of the name you used when registering the element with customElements.define(). You will need it when defining the tag name while adding the element in the editor. In our example, the name is my-custom-element.

Host the Custom Element with Wix Using Velo

You can host the custom element's JavaScript file with Wix using Velo (recommended) or on your own external or local server. 

If you are working in Wix Editor, you must turn on Velo Dev Mode to host with Wix. This step is not necessary in Wix Studio.

When you host with Wix, the default location for your custom element Javascript files is in a folder called custom-elements under the Public section of your site's backend code.

You create custom element JavaScript files:

• By creating the file in an IDE and then manually uploading the file to the custom-elements folder on your site.
• When adding the custom element in the editor by clicking Choose Source > Velo File.
• By modifying the sample template file wix-default-custom-element.js provided by Velo.

Add the Custom Element in the Editor

First review the general instructions for adding a custom element in the editor. 

When using Wix to host, or Velo to enhance the custom element, do the following:

Set the Location of the JavaScript File

In the element's Settings, configure the custom element so it connects to the corresponding JavaScript file.

When you choose Velo file, Velo creates the default Public > custom-elements folder if it doesn't exist yet.

When you create a new file, it is by default called wix-default-custom-element.js. The file automatically contains a template of a custom element that you can change.

Configure the Tag as Registered

Enter the tag name. The tag name corresponds to the element name registered using the define() function in the custom element code.

Code the Behaviors with Velo

Custom element behaviors are coded both in the custom elements' Javascript file and also in Velo. 

You can customize how the custom element behaves for a single page on the site or for all pages on the site. 

Make sure to set up event handlers using the on() function for the events defined in the custom event's Javascript file.

Create and set attributes on the custom element using setAttribute(). This is Velo's way of "communicating" with the custom element. We can pass the custom element attributes and their values so that the custom element's implementation can behave accordingly.

Examples

Get a hands-on introduction to custom elements with our Hello Custom Element example page.

Check out these articles that demonstrate how to work with custom elements, and get ideas for what you can do:  

• Basic "Hello World" example
• Basic example with images  
• Robust example with Velo 
• Template example

See more examples on the Velo by Wix Explore Examples site, such as: 

• Chart.js custom element example
• Dropdown custom element example