Skip to main content

Usage

Xyba Elements are built as custom elements. You can use them as any other HTML element and they are supported by all web frameworks that renders HTML.

If you’re new to custom elements, often referred to as “web components,” this section will help you avoid some of the "quirks" associated with using custom elements.

Wait for Components to Load​

Custom elements are laoded using Javascript, which might lead to a Flash of Undefined Custom Elements (FOUCE) when the page loads, as the elements are not registered at this time.

This can be avoided in CSS using the :defined pseudo-class to hide elements until they are defined.

:not(:defined) {
  visibility: hidden;
}

The CSS technique is simple, but can cause the layout to shift when the elements are registered and initialized.

If this is a concern of yours, you can use customElements.whenDefined() to await all elements before showing anything.

body {
    opacity: 0;
}

body.ready {
    opacity: 1;
}
import 'xyba-elements/elements/analog/analog.js';
import 'xyba-elements/elements/button/button.js';

await Promise.allSettled([
    customElements.whenDefined('xyba-analog'),
    customElements.whenDefined('xyba-button'),
]);

document.body.classList.add('ready');

Don’t Use Self-closing Tags​

Custom elements cannot have self-closing tags. Similar to <script> and <textarea>, you must always include the full closing tag.

<!-- Don't do this -->
<xyba-analog />

<!-- Always do this -->
<xyba-analog></xyba-analog>

Insert elements via Javascript​

As native Html elements, custom elements can be inserted into the DOM via Javascript.

import 'xyba-elements/elements/button/button.js';

const myButton = Object.assign(document.createElement("xyba-button"), {
    innerHTML: "A"
    onpress: () => console.log("button press");
})

document.body.append(myButton)

Page recommendations for touch​

Safari on iOS has features like, long-press to search and context menus. It's recommendable to disable this for a good gaming experience.

Prevent zoom on double tap​

Prevents iOS Safari to zoom in the whole page which is very difficult to reverse if the body has overflow hidden.

document.body.addEventListener('touchstart', e => e.preventDefault());

Prevent context menu​

Prevents the browser from opening the "right-click" menu from long-press.

document.body.addEventListener('contextmenu', e => e.preventDefault());

Prevent zoom bubble​

iOS shows a bubble with the content underneath zoomed in. Xyba Elements already takes care of this, but it's recommendable to apply it to the full layout.

* {
  touch-action: none;
}

Prevent scrolling​

Scrolling on iOS Safari throttles the javascript execution, which causes the controls to be unresponsive while scrolling.

body {
  overflow: hidden;
}