Custom Web Components

Oxidoc lets you register Vanilla JS Web Components as an escape hatch for UI that doesn't need the Wasm pipeline.

Configuration

Map component tag names to JavaScript file paths in oxidoc.toml:

oxidoc.tomltoml

[components.custom]
PromoBanner = "assets/js/promo-banner.js"
FeedbackWidget = "assets/js/feedback-widget.js"

Writing a Component

Each JS file should define and register an HTML Custom Element:

assets/js/promo-banner.jsjavascript

class PromoBanner extends HTMLElement {
  connectedCallback() {
    const message = this.getAttribute('message') || 'Check this out!';
    this.innerHTML = `<div class="promo-banner">${message}</div>`;
  }
}

customElements.define('promo-banner', PromoBanner);

Using in RDX

Use the component tag in your .rdx files just like any built-in component:

docs/intro.rdxmarkdown

<PromoBanner message="New release available!" />

Custom components bypass the Wasm hydration pipeline entirely. Oxidoc renders the HTML element directly and loads your JS file with <script type="module" async>.

When to Use

Use Custom Components

Use Built-in Components

Attributes

All attributes you pass to the component in RDX are forwarded as HTML attributes on the custom element. Your JS connectedCallback can read them with this.getAttribute().