jsx-native

A lightweight JSX runtime that returns real DOM elements instead of a virtual DOM — an efficient alternative to document.createElement for building nested DOM structures without a framework like React.

Table of Contents

• Key Features
• Installation
• Setup
• Usage
  • Basic JSX
  • Event Handlers
  • Class Names
  • Inner HTML
  • Fragments
  • Refs
  • Web Components
• JSX vs. Vanilla DOM

Key Features

| Feature | Details | | ----------------------- | ---------------------------------------------------------------------------------------- | | Real DOM output | JSX expressions return actual HTMLElement instances | | Event props | Native event names prefixed with on (e.g. onclick) | | Flexible event handlers | Single handler, array of handlers, or handlers with options | | Flexible class names | class / className accepts a string or array of strings; falsy values are filtered | | Safe inner HTML | setInnerHTML replaces React's dangerouslySetInnerHTML | | Fragments | <Fragment /> or <></> returns a DocumentFragment | | Direct prop assignment | Props that match a property on the element instance are set directly (not as attributes) |

Installation

npm install @static-bolt/jsx-native

Setup

TypeScript

Add the following to your tsconfig.json:

{
  "compilerOptions": {
    "jsx": "preserve",
    "jsxImportSource": "@static-bolt/jsx-native"
  }
}

Babel

Use @babel/preset-react or @babel/plugin-transform-react-jsx with the automatic runtime.

Using @babel/preset-react:

{
  "presets": [["@babel/preset-react", { "runtime": "automatic", "importSource": "@static-bolt/jsx-native" }]]
}

Using @babel/plugin-transform-react-jsx:

{
  "plugins": [["@babel/plugin-transform-react-jsx", { "runtime": "automatic", "importSource": "@static-bolt/jsx-native" }]]
}

Usage

Basic JSX

JSX expressions return the actual DOM element, so you can cast them directly to the appropriate type:

const btn = (<button>Click me</button>) as HTMLButtonElement;

This is equivalent to:

const btn = document.createElement("button");
btn.textContent = "Click me";

Event Handlers

Event props follow the same naming convention as native DOM events, prefixed with on (e.g. onclick, onchange).

They accept three forms:

Single handler:

<button onclick={handleClick}>Click me</button>

Array of handlers:

<button onclick={[handleClick, trackClick]}>Click me</button>

Array of handlers with addEventListener options:

Each entry is a tuple of [handler, options]:

<button
  onclick={[
    [handleClick, { once: true }],
    [trackClick, { passive: true }],
  ]}
>
  Click me
</button>

Class Names

The class and className props accept a string or an array of strings. Falsy values in arrays are ignored automatically, making conditional classes straightforward:

<div class="container" />
<div class={["btn", isActive && "btn--active", isDisabled && "btn--disabled"]} />

Inner HTML

Use setInnerHTML to set raw HTML content on an element:

const content = <div setInnerHTML="<strong>Hello</strong>" />;

Warning: Only use setInnerHTML with trusted content. Injecting user-provided HTML can expose your application to XSS attacks.

Fragments

Use <Fragment /> or the shorthand <></> to group elements without adding an extra node to the DOM. Both return a DocumentFragment:

import { Fragment } from "@static-bolt/jsx-native";

const items = (
  <>
    <li>First</li>
    <li>Second</li>
  </>
) as DocumentFragment;

Refs

Use createRef to obtain a reference to a DOM element nested inside a JSX tree.

Extracting a reference:

import { createRef } from "@static-bolt/jsx-native";

const btnRef = createRef<HTMLButtonElement>();

const container = (
  <div>
    <button ref={btnRef}>Click Me</button>
  </div>
) as HTMLDivElement;

const btn = btnRef.current; // HTMLButtonElement

Inline callback ref:

Pass a function directly to ref to act on the element immediately when it is created:

const container = (
  <div>
    <button ref={node => node.focus()}>Click Me</button>
  </div>
) as HTMLDivElement;

Web Components

When a prop name matches an existing property on the element instance (e.g. a Web Component's reflected property), jsx-native sets it directly via property assignment instead of setAttribute:

<my-slider value={42} />
// equivalent to: element.value = 42

This ensures correct behavior for properties that are not serializable as attributes.

JSX vs. Vanilla DOM

The example below shows how the same component looks with and without JSX.

With JSX:

import { createRef } from "@static-bolt/jsx-native";

interface Props {
  title?: string;
  onclick?: (event: MouseEvent) => void;
  children?: HTMLElement[];
}

export function ButtonWithIcon({ title, onclick, children }: Props) {
  return (
    <button type="button" class="button" onclick={onclick}>
      <span>{title}</span>
      <span>🚀</span>
      {children}
    </button>
  ) as HTMLButtonElement;
}

Without JSX:

interface Props {
  title?: string;
  onclick?: (event: MouseEvent) => void;
  children?: HTMLElement[];
}

export function ButtonWithIcon({ title, onclick, children }: Props): HTMLButtonElement {
  const button = document.createElement("button");
  button.type = "button";
  button.className = "button";

  if (onclick) {
    button.addEventListener("click", onclick);
  }

  const titleSpan = document.createElement("span");
  titleSpan.textContent = title ?? "";
  button.appendChild(titleSpan);

  const iconSpan = document.createElement("span");
  iconSpan.textContent = "🚀";
  button.appendChild(iconSpan);

  if (children) {
    children.forEach(child => button.appendChild(child));
  }

  return button;
}

License

@static-bolt/jsx-native library is licensed under The MIT License.