Velo: Custom Element FAQs
General
Why Use a Custom Element Instead of an iFrame?
See this matrix comparing the different ways you can add custom code elements to your site and the benefits of each.
Can I Use "Out-of-the-Box" Custom Elements from Other 3rd-party Sources?
Yes! You don't have to create your own.
Just make sure to update the Tag Name in Properties when adding the custom element to your page.
Can I Use Velo APIs in My Custom Element?
No. Do not use any Velo APIs in your custom element. Only code using the standard ECMAScript 2015 class syntax can be used to define a custom element. See the MDN documentation.
SEO (Velo Only)
Do Web Crawlers Index Custom Elements if I Don't Define SEO Markup?
Without defining SEO Markup, only web crawlers that index JavaScript, such as Google, will be able to index the custom element.
If you define SEO Markup, all web crawlers can index the custom element based on the markup text you enter.
How Can I Make Sure My SEO Markup Is Not Misconstrued as Cloaking?
To make sure that web crawlers do not misinterpret your SEO Markup as an attempt to distort search engine rankings, make sure that the code of your element matches the SEO Markup exactly.
Hosting
Where Can I Host Custom Elements?
You can use Velo to host your custom elements (recommended).
Alternatively, you can use your own external or local server for hosting your custom elements.
If I Host with Velo, Where Do I Store My Custom Element?
The default location for your custom element Javascript files is:
Public\custom-elements
If I Host with Velo, What is the URL of the JavaScript File?
You might want to access a custom element JavaScript file hosted by Wix Velo for:
- Editing, testing and debugging.
- Sharing it with another Wix site or on another project.
You can get the URL for any of your custom element JavaScript files using your browser's Developer Tools console. For example, in Chrome, click the Network tab and search for the name of your file. The URL is displayed in the Headers sub-tab or if you hover.
How Can I Create a Server for Hosting Custom Elements (Optional)?
You can set up, or get access to, a server for your custom elements. If you want to host your custom elements with Wix, skip this step.
If you are hosting on localhost
, you can use HTTP (you might need to change browser settings). If you are hosting on an external server, this requires secure HTTPS.
Setting up a Server Locally with npm
Providing complete instructions for creating a server is outside of the scope of this article. But we can help get you started by giving you some instructions for creating a server on your local machine:
In a command prompt window, do the following:
- Create a folder for your custom elements on your local machine.
- Enter npm i -g serve to install the serve software.
- Run serve <**custom-element-folder**> to start the server.
- Copy the server's address, such as http://localhost:5000, to use when adding the custom element in the Wix Editor.
Where Do I Store Images for Custom Elements?
If you want your custom element to contain your own images, upload them to your Wix Media Manager or to any other image hosting site.
Copy the URL of the image. You will use this URL when implementing the new custom element.
Getting the URL from the Wix Media Manager
- Click Media
on the left side of the Editor.
- If the image has been uploaded already, you will see it under Site Files. Click Show More.
- Right-click the image, and choose Copy URL.
Coding the Custom Element
How Does My Custom Element Notice Events on My Site?
Custom elements react to:
- DOM-related events. When you create your custom element, use MDN lifecycle callback functions such as
connectedCallback()
andattributeChangedCallback()
. These functions look out for DOM-related events. - Wix-related events.
$w.onReady()
notifies the custom element when the page is ready.
Coding in Velo
Can I Connect Custom Elements to Data in a Collection?
Yes, you can connect custom elements to collections using Velo's Data and Dataset APIs.
Troubleshooting
Why Does My Custom Element Change the Page Layout?
Adding elements to your site can affect the page height and layout. Learn more about how elements can impact your page layout.
Why Does My Custom Element Look Different in Preview and when Published?
For security reasons, the custom element is rendered inside an iFrame inside the Editor and in preview mode. This might affect the layout of the custom element. Go to your published site to see how it actually looks on your live site. You can also use test sites as a preview.
Why Can't I See My Custom Element on My Live Site?
There are a few requirements for working with custom elements. Make sure your site meets these requirements.
General Requirements and Guidelines
- When hosting externally, make sure that:
- Your link to the custom element URL contains HTTPS, not HTTP.
- The server URL includes the JavaScript file name.
- The custom element's JavaScript file contains the core elements of the page, but other design settings are probably stored separately in a CSS, for example. Therefore, some elements may not function or look the same if the relevant elements aren’t included in the custom element's JavaScript file. You may have to duplicate style elements that you need in the custom element's JavaScript file to avoid this issue.
- Always make sure the custom element code is up-to-date and HTML5-compatible. Most browsers don't display pages and scripts properly if they were written using older versions of JavaScript.
Get a Domain and Remove Wix Ads
Only premium Wix users on sites with their own domain and with Wix ads removed can work with custom elements. Make sure your premium package is set up this way.
Check Browser Security Settings
Make sure that your browser's security settings enable communication between the local machine on which you are working with Velo and the server that is hosting the custom element implementation. For instructions, see your browser documentation.
Chrome Tips
If you are working in Chrome, and you get messages similar to "This page is not secure," you can try adjusting Chrome's experiment settings:
- In the URL, enter chrome://flags.
- Disable Mark non-secure origins as non-secure.
- Enable Allow invalid certificates for resources loaded from localhost.
- Relaunch Chrome.