Introduction
Last updated
Last updated
WebComp.js is a "batteries included" JavaScript library for writing smart reusable Web Components in a modern way.
Inspired by React components, WebComp provides familiar state management mechanisms and Virtual DOM, while also providing all of the sweetness of Web Components like Shadow DOM, server side rendering placeholders and ability to render from a string.
Here's how to get started with WebComp:
Looks familiar? WebComp components are written in the exact same way as React components.
Note: Because WebComp uses Preact for rendering JSX, props
and state
are passed as arguments to the render()
method for convenient destructuring. You can still use this.props
and this.state if you want to, but it's not required.
Second argument is an optional tag name. If not set, component name converted to dash-case will be used.
And you're good to go! Custom tag's attributes will be passed to `this.props` in your component and resulting HTML on the page will be:
Yes, you can! The above class example can be trimmed down to this:
A third argument passed to WebComp.register
is an options object:
useShadow
- Enable Shadow DOM. Pass open for open mode and closed for closed. See the difference here.
allowScripts
By default, all <script>
tags will be removed from rendered markup. This option re-enables them and permits executing any JavaScript code within a component. Be careful with this option.
There are 3 ways to enable JSX with WebComp:
You can specify a JSX pragma either in individual files using
or
at the top of the file containing JSX. This will tell Babel to turn all JSX calls into `WebComp.h` calls. This is useful if for instance you already have React in your project and don't wan't to overwrite all of JSX behavior.
.babelrc
WebComp is written with the web platform in mind. According to WebComponents.org, the current support for platform features is as follows:
Browser Support | Chrome | Opera | Safari | Firefox | Edge |
Template Tags | ❇️ Stable | ❇️ Stable | ❇️ Stable | ❇️ Stable | ❇️ Stable |
Custom Elements | ❇️ Stable | ❇️ Stable | ❇️ Stable | ❇️ Stable | 🛠 Developing ☘️ Polyfill |
Shadow DOM | ❇️ Stable | ❇️ Stable | ❇️ Stable | ❇️ Stable | 🛠 Developing ☘️ Polyfill |
ES Modules | ❇️ Stable | ❇️ Stable | ❇️ Stable | ❇️ Stable | ❇️ Stable |
Note: WebComp does not include any polyfills. You are responsible for pollyfilling for your target browsers.
WebComp also supports rendering from string via stateless functional components. We'll get to that in a bit. However using JSX provides a whole lot of awesome features that you'll be missing out on.
WebComp doesn't impose any build systems on you. All you need to get started is drop a script tag on the page.
The downside of not using a build system is unavailability of JSX via Babel. But you can still use string render and get all benefits of Virtual DOM, or use WebComp.h
directly to create components.
Unfortunately WebComp doesn't support template tag rendering at the moment.
Nope. WebComp is inspired by React components approach and uses Preact under the hood for features like Virtual DOM and state management, but it's not React nor does it require it.
Yes! By default all elements inside your custom tag will be passed to this.props.children
. There's a flag to disable that behavior.
Yes! WebComp supports infinite levels of component-ception, although it's recommended to use JSX for nesting things.
WebComp is your friend! If outside forces like jQuery decide to change your element's attributes, changes will be passed down to this.props
and componentWillReceiveProps
will be called as you would expect.
Probably not, since WebComp doesn't use React. Using preact-compat in your build chain can help since WebComp uses Preact under the hood, but no promises.
Whoa whoa, hold your horses. WebComp serves different purpose than React or Angular or Vue or what have you. You're not supposed to be building an SPA with this.
WebComp is not an SPA framework, it's a Web Components library.
Web components are a set of web platform APIs that allow you to create new custom, reusable encapsulated HTML tags to use in web pages and web apps.
What WebComp does is allows you to create components that are smarter than just a collection of tags and styles and allow you to do things like interactions, networking, etc.
If you want to build a dynamic single page app, this library is probably not the droid you're looking for.