@biotope/element

Biotope Element

biotope-element is a library to create Web Components in a simple way, taking advantage of simple yet powerful concepts from other frontend libraries to empower you, the developer, and your clients' needs - be them integration with popular CMSs or developing amazing design-systems to be used anywhere.

biotope-element uses mostly vanilla web technologies and is built with the intention of being used for component development and not page assembly. This means we dedicate ourselves to making sure that page assembly libraries like React, Vue or Angular have the best possible experience when using our components. This also means that every piece of knowledge you have about HTMLElements is applicable when working with biotope-element.

Documentation

You can find the full documentation here.

In order to contribute to the documentation you can start a local server with npm start and then start editing the files in docs.

Installation

You can install the biotope element in your project using npm:

npm install @biotope/element

or yarn

yarn add @biotope/element

After that, import it in your components like so:

import Component from '@biotope/element';

Alternatively you can use unpkg to insert biotope-element into your HTML for quick testing through our minified ES5 file available here.

Your first component

To use biotope-element, you have to extend it with your custom class.

After defining your class, you have to call the register function. Here's a minimal example of a working component:

// my-button.js
import Component from '@biotope/element';

export class MyButton extends Component {
  render() {
    return this.html`
      Hello World 🐤
    `;
  }
}

MyButton.componentName = 'my-button';
MyButton.register();

After that you can use it in your html like so:

<script src="my-button.js"></script>
<my-button></my-button>

This will result in the following html:

<script src="my-button.js"></script>
<my-button>
  Hello world 🐤
</my-button>

📝 Note: It's irrelevant where the script is placed. But remember that the component will only start to render after the script is parsed and the component is registered.

Compatibility and Polyfills

Natively, Web Components are not supported by all browsers - this includes biotope-element. You can check out a list of compatible browsers using caniuse.

To get it to work on almost all non-dead browsers, you can use these polyfills. You can also checkout their npm package or you can simply put a script pointing to unpkg which will load only the necessary polyfills.

⚠️ Important: Remember to make sure that the polyfill is fully loaded before attempting to register any component. This is done via the WebComponentsReady event or by a blocking script tag.