https://github.com/brikcss/element
Brikcss Element extends the awesomeness of native Web Components. Brikcss Element is a super light-weight wrapper around Custom Elements (part of Web Components), and extends its features and makes elements easy to develop.
https://github.com/brikcss/element
Last synced: 2 months ago
JSON representation
Brikcss Element extends the awesomeness of native Web Components. Brikcss Element is a super light-weight wrapper around Custom Elements (part of Web Components), and extends its features and makes elements easy to develop.
- Host: GitHub
- URL: https://github.com/brikcss/element
- Owner: brikcss
- License: mit
- Created: 2019-04-01T23:04:11.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2020-06-02T18:34:02.000Z (about 5 years ago)
- Last Synced: 2025-03-28T23:36:07.656Z (3 months ago)
- Language: JavaScript
- Homepage:
- Size: 9.12 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Support: docs/supporting-legacy-browsers.md
Awesome Lists containing this project
README
# 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"](https://semver.org/#spec-item-4).**
Native Web Components provide [many](https://duckduckgo.com/?q=why+native+web+components) [amazing](https://codeburst.io/6-reasons-you-should-use-native-web-components-b45e18e069c2) [benefits](https://duckduckgo.com/?q=benefits+of+native+web+components) traditionally only found in frameworks like Angular, Vue, or React. Web Components, however, have [many advantages over these types of frameworks](https://duckduckgo.com/?q=web+components+or+framework), and [should eventually replace them](https://blog.usejournal.com/web-components-will-replace-your-frontend-framework-3b17a580831c). 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](./CONTRIBUTING.md) and get involved to support this project.**
## Browser Support\*
| Chrome | Firefox | Safari | Edge | IE |
| ------ | ------- | ------ | ---- | ------ |
| ✓ | ✓ | ✓ | ✓ | 11\*\* |
\*_With the [proper polyfills](#getting-started)._
\*\*_IE11 can be supported with a transpiled build for legacy browsers._
## Install
**From NPM:**
```bash
npm install -D @brikcss/element
```
**From GitHub:**
Download the [latest release](https://github.com/brikcss/element/releases/latest).
## Getting Started
1. Include Web Components polyfills. We recommend [webcomponentsjs](https://github.com/webcomponents/webcomponentsjs), included with Brikcss Elements.
```html
```
_[Learn more about this and other Web Components polyfills](./docs/web-components-polyfills.md)._
2. [Decide which Brikcss Element build you will use](./docs/including-brikcss-modules.md). _For simple prototypes/demos, feel free to use the Browser Module. For production applications we strongly encourage the Vanilla Module._ [Why?](./docs/including-brikcss-modules.md)
3. Include it and extend it:
```js
// 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](#brikelement)._
4. Define your custom element:
```js
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:
```html
...
```
## API
### Module Exports
#### `default`
The default export returns a class that extends `HTMLElement`. Use as follows:
```js
// 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`):
```js
// 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](https://github.com/ungap/custom-elements-builtin) 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:
```js
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](./docs/creating-mixins.md)._
### 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](https://www.dannymoerkerke.com/blog/web-components-will-replace-your-frontend-framework)
- [MDN web docs: Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components)
- [Google Web Fundamentals: Building Components](https://developers.google.com/web/fundamentals/web-components/)