Velo: About Custom Elements
5 min
In this article
- How to Create Custom Elements
- Prerequisites
- Code the Custom Element
- Host the Custom Element with Wix Using Velo
- Add the Custom Element in the Wix Editor
- Set the Location of the JavaScript File
- Configure the Tag as Registered
- Code the Behaviors with Velo
- Examples
Custom elements let you add custom elements to your site that are not currently available "out of the box" with the Wix Editor. Custom elements are available from the Embed Code section of the Add 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.
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.
Important
Only premium Wix users on sites with their own domain and Wix ads removed can work with custom elements.
How to Create Custom Elements
Here is an outline of the steps for adding custom elements:
- Check prerequisites.
- Code the custom element.
- Host the JavaScript file.
- Add a custom element to your site.
- 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:
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.
Note
We assume you know a bit about designing elements with CSS properties in Javascript and working with web components.
This article provides basic instructions only. For full instructions and examples about using web components, which are the basis of custom elements, see the MDN documentation.
This article provides basic instructions only. For full instructions and examples about using web components, which are the basis of custom elements, see the MDN documentation.
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.
Note
Do not use any Velo APIs in your custom element.
Create a class for the custom element and register the custom element.
Here is a sample code snippet:
Here is a sample code snippet:
1class MyCustomElement extends HTMLElement {
2 constructor() {
3 super();
4 console.log(...);
5 }
6
7 connectedCallback() {
8 ...
9 ...
10 ...
11 }
12}
13customElements.define('my-custom-element', MyCustomElement);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.
To host with Wix, you must turn on Velo Dev Mode.
To host with Wix, you must turn on Velo Dev Mode.
When you host with Wix, the default location for your custom element Javascript files will be: Public/custom-elements/
You create custom element JavaScript files:
- By creating the file in an IDE and then manually uploading the file to
Public/custom-elements/in the Site Structure sidebar. - When adding the custom element in the Wix Editor by choosing New File.
- By modifying the sample template file
wix-default-custom-element.jsprovided by Velo.
Add the Custom Element in the Wix Editor
First review the general instructions for adding a custom element in the Wix Editor.
When using Wix to host, or Velo to enhance the custom element, do the following:
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.
Note
This illustration shows hosting by Wix using a Velo file. You can also host using an external or local server URL.
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.
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.
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:
See more examples on the Velo by Wix Explore Examples site, such as:
Hire a Velo Web DeveloperNeed a little extra help with your site? Hire a developer from the Wix Marketplace to build and deploy advanced web applications.
