Introduction

WebComp.js

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.

Getting Started

Here's how to get started with WebComp:

1. Install WebComp:

npm install @webcomp/core

2. Import WebComp:

import { WebComponent, register } from '@webcomp/core';

3. Create your component:

class SuperHeader extends WebComponent {
  render(props) {
    return (
      <div>
        <h1>{props.text}</h1>
        <h3>It's Superpowered!</h3>
      </div>
   );
  }
}

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.

4. Register your custom tag:

register(SuperHeader, 'super-header');

Second argument is an optional tag name. If not set, component name converted to dash-case will be used.

5. Use it!

<div id="main">
  <super-header text="This is not a simple header!"></super-header>
</div>

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:

<div>
  <h1>This is not a simple header!</h1>
  <h3>It's Superpowered!</h3>
</div>

Can I use stateless functional components?

Yes, you can! The above class example can be trimmed down to this:

const SuperHeader = ({ text }) => (
  <div>
    <h1>{text}</h1>
    <h3>It's Superpowered!</h3>
  </div>
);

Options

A third argument passed to WebComp.register is an options object:

{ useShadow: 'open' || 'closed', allowScripts: true}

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.

Notes on JSX

There are 3 ways to enable JSX with WebComp:

Using a Babel preset (easiest)

// .babelrc
{
  "presets": ["@webcomp/babel"]
}

By defining a JSX pragma

You can specify a JSX pragma either in individual files using

/** @jsx WebComp.h */

or

/** @jsx h */
import { h } from '@webcomp/core';

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.

Using .babelrc

{
  "presets": [...],
  "plugins": [
    "transform-react-jsx",
    {
      "pragma": "WebComp.h" // default pragma is React.createElement
    }
  ]
}

What browsers are supported?

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.

FAQ

I'm morally opposed to JSX. How can I use this?

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.

I'm morally opposed to Webpack and bundling! How can I use this?

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.

Can I use template tags and slots?

Unfortunately WebComp doesn't support template tag rendering at the moment.

Do I need React to use this?

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.

Can I have content inside of my custom elements?

Yes! By default all elements inside your custom tag will be passed to this.props.children. There's a flag to disable that behavior.

Can I have custom elements inside of my custom elements?

Yes! WebComp supports infinite levels of component-ception, although it's recommended to use JSX for nesting things.

I am morally supportive of imperative DOM manipulations. Will this still work?

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.

Can I use React library XYZ to do ZYX?

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.

How do I port my single page app to WebComp?

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.