Brikcss Element

About

[ IMPORTANT ]: Brikcss Element follows semantic versioning. Since it is currently at major version zero, "anything may change at any time", and it "should not be considered stable".

Native Web Components provide many amazing benefits traditionally only found in frameworks like Angular, Vue, or React. Web Components, however, have many advantages over these types of frameworks, and should eventually replace them. The challenge with Web Components is that they are new and have a fair amount of boilerplate to write custom elements and components. Enter Brikcss Element.

Brikcss Element is a super lightweight framework that simplifies and extends the awesomeness of native Web Components. At its core, Brikcss Element has two primary goals:

1. To extend the power and features of Web Components in a way that allows developers and end users to easily implement only features they need.

2. To simplify where possible, but not replace or heavily abstract, commonly used features in Web Components. In other words, make TTFC ("time to first component") quick and easy.

Brikcss Element strives for a very small learning curve for newbies, while also providing a high level of power and flexibility.

Contributing

We ❤️❤️❤️ contributions of any kind, whether it's bug reports, questions or feature requests, pull requests, and especially spreading some love about this project to your friends and co-workers!

Read our contributing guidelines and get involved to support this project.

Browser Support*

| Chrome | Firefox | Safari | Edge | IE | | ------ | ------- | ------ | ---- | ------ | | ✓ | ✓ | ✓ | ✓ | 11** |

*With the proper polyfills. **IE11 can be supported with a transpiled build for legacy browsers.

Install

From NPM:

npm install -D @brikcss/element

From GitHub:

Download the latest release.

Getting Started

1. Include Web Components polyfills. We recommend webcomponentsjs, included with Brikcss Elements.

   <script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>

   Learn more about this and other Web Components polyfills.

2. Decide which Brikcss Element build you will use. For simple prototypes/demos, feel free to use the Browser Module. For production applications we strongly encourage the Vanilla Module. Why?

3. Include it and extend it:

   // app.js
   // ------
   // 1) Include it:
   //    Vanilla module:
   import BrikElement from '@brikcss/element';
   //    Browser module:
   import BrikElement from 'node_modules/@brikcss/element/dist/esm/brik-element.browser.js';
   //    Universal module:
   const BrikElement = brikcss.default;
   
   // 2) Extend it:
   class MyElement extends BrikElement {
       constructor(...args) {
           // If you have a constructor, always call super first.
           super(args);
           // Your constructor code...
       }
       // Define class methods/properties here...
   }

   Note: The default export automatically extends HTMLElement. If you want to extend a different built-in element (i.e., HTMLAnchorElement), use the BrikElement named export.

4. Define your custom element:

   MyElement.define('my-element', options);
   // which is equivalent to:
   window.customElements.define('my-element', MyElement, options);

   Note: Per Custom Elements specifications, all custom element tags must have at least one hyphen (-).

5. Finally, use your custom element:

   <my-element>...</my-element>

API

Module Exports

default

The default export returns a class that extends HTMLElement. Use as follows:

// ES module (use relative path for Browser module):
import BrikElement from '@brikcss/element'
// or Universal module:
const BrikElement = brikcss.default
// and then:
class MyElement extends BrikElement {...}

Note: The default export is equivalent to calling the BrikElement named export as follows: BrikElement(HTMLElement).

BrikElement

The only named export is BrikElement, which allows you to extend built-in HTML Elements (such as HTMLAnchorElement):

// ES module (use relative path for Browser module):
import { BrikElement } from '@brikcss/element'
// or Universal module:
const BrikElement = brikcss.BrikElement
// and then:
class MyElement extends BrikElement(HTMLAnchorElement) {...}

Now your element will inherit all the properties of a built-in anchor tag element! Note: You may need to use a polyfill for extending built-in elements for this to work in some browsers.

Static methods

BrikElement.define(tagName, options = {})

A simple shortcut/alternative to window.customElements.define().

• tagName (String): Name of custom element to be defined. String must be hyphenated.
• options (Object): Configuration options passed to window.customElements.define.

BrikElement.with(...mixins)

Mixins give BrikElement its power. To apply one or more mixins, simply pass them to the BrikElement.with() method:

import BrikElement from '@brikcss/element'
import MyMixin from 'my-mixin.js'
class MyElement extends BrikElement.with(MyMixin) {...}

Note: You can apply existing mixins or create your own.

Instance properties

this.root

Simple getter/setter which returns (or sets) the root element. By default, this will be this.shadowRoot or this, depending on whether shadowRoot has been attached.

Resources

Web Components

• Web Components will replace your frontend framework
• MDN web docs: Web Components
• Google Web Fundamentals: Building Components