Better React Web Component

Wrapper for React (v18.x) Component to CustomElement that magically just works and is type safe with Typescript!

• Small. About 1kB (minified and gzipped). Zero dependencies.
• Simple. Each component interface is defined with strict types.
• Good TypeScript support.

import { createCustomElement, InferProps, optional } from 'better-react-web-component'

// Define custom component interface
HelloComponent.types = {
  name: optional.string,
}

// Infer typescript types
type ComponentProps = InferProps<typeof HelloComponent.types>

// Defined component
function HelloComponent({ name = "unknown" }: ComponentProps) {
  return (
    <h1>Hello {name}!</h1>
  )
}

// Create and register custom component
customElements.define(
  "hello-component",
  createCustomElement(HelloComponent, "shadowRoot"),
)

Usage in html:

<hello-component name="World" />

Open this demo in dune.land

Install

npm install better-react-web-component

Guide

Define attributes

Attributes are defined on component types object.

Note Attribute names defined here are case-insensitive as they are in HTML spec! Hence the below can be used as <component name="..." /> or <component nAmE="..." />.

MyReactComponent.types = {
  name: optional.string,
  requiredName: required.string,
}

Supported prop types:

• String:
  • optional.string
  • required.string
• Number:
  • optional.number
  • required.number
• Boolean:
  • optional.boolean
  • required.boolean
• Json (parses attribute with JSON.parse):
  • optional.json
  • required.json
• Function:
  • optional.event
  • required.event

Define default values

Default values are defined on react component itself.

function MyReactComponent({
  requiredName,
  name = "unknown",
}: InferProps<typeof MyReactComponent.types>) {
  ...
}

Handle json/object values

In webcomponent space there is no object type to be passed as value. Instead we can pass json object as string and then parse it in react component. For this we can use optional.json or required.json (it does parsing automatically so component will receive object not string).

And for Typescript to have proper types we can use InferProps feature to replace/update properties like json values.

MyReactComponent.types = {
  custom: required.json,
}

type Props = InferProps<typeof MyReactComponent.types, {
  custom: {
    foo: string;
    bar: number;
  }
}>

Then in component this object can be passed as string

<my-react-component custom='{"foo":"one","bar":2}' />

Handle events

This package also supports custom events to be defined.

Note Event names defined here are CASE-SENSITIVE so we lowercase them and remove leading "on" to match other event names!

import { createCustomElement, InferProps, optional } from 'better-react-web-component'
import { useState } from 'react'

InputName.types = {
  name: optional.string,
  onNameChange: optional.event, // Event name must start with "on" and will be lowercase in html land
}

function InputName({
  name = 'unknown',
  onNameChange,
}: InferProps<typeof InputName.types>) {
  const [localName, setLocalName] = useState(name)

  return (
    <input
      value={localName}
      onChange={(e) => {
        setLocalName(e.target.value)
        onNameChange?.({ detail: e.target.value }) // Trigger custom event here if it's defined
      }}
    />
  )
}

customElements.define('input-name', createCustomElement(InputName))

At the same time in html land:

<input-name name="World" />
<script>
  const inputNameEl = document.querySelector('input-name');

  // Note that event name is ALWAYS lowercase without `on` in front of it
  inputNameEl.addEventListener('namechange', (e) => {
    console.log(e.detail);
  });
</script>

Open this demo in dune.land