Getting started

Quick start

The Elix documentation for components like DateComboBox show live demos of Elix components running in your browser. To see an Elix component in action on a local web page, enter the following in a terminal window:

git clone https://github.com/elix/plain-example.git
cd plain-example
npm install
npx http-server

Then open http://localhost:8080 to view the sample page.

Instantiating web components in markup

Web components like the ones in the Elix library are defined as JavaScript classes that you can manipulate as markup in HTML or directly in your JavaScript/TypeScript code.

You can make Elix components available in HTML simply by loading a JavaScript module from the Elix project using a script tag, as shown here:

<html>
  <head>
    <script
      type="module"
      src="./node_modules/elix/define/DateComboBox.js"
    ></script>
  </head>
  <body>
    <elix-date-combo-box date="1 Jan 2020"></elix-date-combo-box>
  </body>
</html>

Once the component module is loaded, you can then instantiate the component with its tag name. The default HTML tag name for the DateComboBox component is elix-date-combo-box. If desired, you can then set properties on the component as attributes, such as date="1 Jan 2020".

Instantiating web components in Javascript

Each Elix component module exposes a default export that you can import into your JavaScript (or TypeScript, etc.) application. You can then instantiate the component with new, set properties or invoke methods on it, and add it to the DOM like a regular HTML element:

// Import the Elix components we want to use.
import DateComboBox from "./node_modules/elix/define/DateComboBox.js";

// Instantiate an Elix component.
const dateComboBox = new DateComboBox();

// You can set custom properties on the component, invoke methods, etc.
dateComboBox.date = new Date("1 Jan 2021");

// We can add the components to the page like any other HTML elements.
document.body.appendChild(dateComboBox);

By default, the Elix components in the projects define folder automatically register themselves with the browser. In the example above, the module at elix/define/DateComboBox.js will register the DateComboBox component as elix-date-combo-box.

If you prefer to register an Elix component with a different name, import the module from the project's src folder instead, then register the component yourself with whatever tag you like by calling the standard customElements.define API:

import DateComboBox from "./node_modules/elix/src/base/DateComboBox.js";
class MyDateComboBox extends DateComboBox {}
customElements.define("my-date-combo-box", MyDateComboBox);
const myDateComboBox = document.createElement("my-date-combo-box");

As shown above, it's recommended that you actually create a simple subclass of the desired component, and then register that, rather than registering the component class directly.

Bundling components for production use

Elix components are written in plain JavaScript, and so they require no build step to be usable! For performance reasons, in production you will generally want to use webpack or some similar bundler to create a smaller set of JavaScript files. When using a bundler, the import statements above can typically be simplified to start with the name of the elix package:

// Import the Elix components we want to use.
import DateComboBox from "elix/define/DateComboBox.js";