react-shadow-dom

Newly available across major browsers (Baseline since 2024)

A utility for the Shadow DOM in React

Caution

Development has been suspended due to the discovery of a critical issue.

Table of Contents

• Table of Contents
• Background
• Install
• Usage
  • Template
  • ShadowRoot
  • Difference
• API
• Contributing
• License

Background

Shadow DOM is a powerful web feature. Slot and style encapsulation work exceptionally well with JSX as templates. Unfortunately, React's Shadow DOM support is limited.

This project provides utilities for working with shadow DOM in React.

Install

Deno:

deno add jsr:@miyauci/react-shadow-dom

Node.js

npx jsr add @miyauci/react-shadow-dom

Usage

This library provides two main components: Template and ShadowRoot.

Template

Provides a method for implementing Declarative Shadow DOM (DSD) in React.

This is <template>. However, it adjusts shadow DOM hydration.

When shadowRootMode is specified, the browser automatically attaches the ShadowRoot. The Template adjusts the VDOM on the client side to prevent hydration errors.

import { Template } from "@miyauci/react-shadow-dom";

<div>
  <Template shadowRootMode="open">
    <style>
      {`* {
  color: gray;
}
`}
    </style>
    <button>
      <slot name="icon" />
      <slot />
    </button>
  </Template>

  <span slot="icon" className="my-icon" />
  Label
</div>;

ShadowRoot

This is a container attached as a shadow root on the client side. In other words, using the ShadowRoot as a boundary, render children into the parent element's shadow root.

import { ShadowRoot } from "@miyauci/react-shadow-dom";

<div>
  <ShadowRoot mode="open">
    <style>
      {`* {
  color: gray;
}
`}
    </style>
    <button>
      <slot name="icon" />
      <slot />
    </button>
  </ShadowRoot>

  <span slot="icon" className="my-icon" />
  Label
</div>;

Difference

Template implements DSD. ShadowRoot implements a client-side-only shadow root.

Note

Note that DSD is newly available across major browsers (baseline since 2024).

API

See deno docs

Contributing

See CONTRIBUTING

License

MIT © Tomoki Miyauchi