Skip to content

Latest commit

 

History

History
375 lines (281 loc) · 10.4 KB

README.md

File metadata and controls

375 lines (281 loc) · 10.4 KB
Raw

jsx-dom

License build status npm version

Use JSX for creating DOM elements. Supports ES Module and TypeScript.

NEW! Styled components are now supported.

Installation

npm install --save jsx-dom
yarn install jsx-dom
pnpm add jsx-dom

Usage

jsx-dom is ESM only. If you need CommonJS support, install jsx-dom-cjs instead. These two packages only differ in module format.

Note: If you are using React Automatic Runtime, simply set jsxImportSource to jsx-dom or jsx-dom/min and you can omit the import.

import React from "jsx-dom"

// DOM Elements.
document.body.appendChild(
  <div id="greeting" class="alert">
    Hello World
  </div>
)

// Functional components
// `defaultProps` and `props.children` are supported natively and work as you expect.
function Hello(props) {
  return (
    <div>
      Hello, {props.firstName} {props.lastName}!
    </div>
  )
}
Hello.defaultProps = {
  firstName: "John",
}

document.body.appendChild(<Hello firstName="Johnny" lastName="Appleseed" />)

// Class components
// `defaultProps` and `props.children` are supported natively and work as you expect.
// In terms of React jsx-dom class components have no state,
// so `render` function will be called only once.
//
// Component lifecycle functions are currently not supported. This may change in
// the future.
class Welcome extends React.Component {
  static defaultProps = {
    firstName: "John",
  }

  render() {
    return (
      <div>
        Welcome, {this.props.firstName} {this.props.lastName}!
      </div>
    )
  }
}

document.body.appendChild(<Welcome firstName="Johnny" lastName="Appleseed" />)

Styled Components

import { styled } from "jsx-dom"

const HeaderText = styled.h2`
  font-size: 20px;
  font-weight: 500;
`

document.body.appendChild(
  <HeaderText style={{ /* you can override here */ }}>
    Welcome!
  </HeaderText>
)

const Name = styled.div<{ large?: boolean }>`
  font-size: ${props => props.large ? 40 : 20}px;
  ${props => props.large ? "font-weight: 600;" : ""}
`

document.body.appendChild(
  <Name large>
    Welcome!
  </Name>
)

Shadow DOM

import { ShadowRoot } from "jsx-dom"

document.body.appendChild(
  <dialog>
    <ShadowRoot mode="closed">
      <style>:root { font-family: Helvetica Neue; }</style>
      <button>Hello</button>
    </ShadowRoot>
  </dialog>
)

Syntax

jsx-dom is based on the React JSX syntax with a few additions:

Class

  1. class is supported as an attribute as well as className.

  2. class can take:

    • a string
    • an object with the format { [key: string]: boolean }. Keys with a truthy value will be added to the classList
    • an array of values where falsy values (see below) are filtered out
    • an array of any combination of the above, including deeply nested arrays

Note that false, true, null, undefined will be ignored per React documentations, and everything else will be used. For example,

<div class="greeting" />
<div class={[ condition && "class" ]} />
<div class={{ hidden: isHidden, "has-item": !!array.length }} />
<div class={[ classArray1, classArray2, ["nested", ["further"]] ]} />

Style

  1. style accepts a string, an object and an array of any combination of the above, including deeply nested arrays. Unitless properties supported by React are also supported.
<div style="background: transparent;" />
<div style={{ background: "transparent", fontFamily: "serif", fontSize: 16 }} />

Children

Passing children as an explicit attribute, when there is no other JSX child node, is also supported. Any object that matches the TypeScript ArrayLike interface can be used as children, including jQuery objects.

<div children={["Total: ", 20]} />

Other Attributes

  1. dataset accepts an object, where keys with a null or undefined value will be ignored.
<div dataset={{ user: "guest", isLoggedIn: false }} />
  1. Attributes starts with on and has a function value will be treated as an event listener and attached to the node by setting the property directly (e.g. node.onclick = ...).
<div onClick={e => e.preventDefault()} />

  1. innerHTML, innerText and textContent are accepted.

  2. ref accepts either 1) a callback (node: Element) => void that allows access to the node after being created, or 2) a React style ref object. This is useful when you have a nested node tree and need to access a node inside without creating an intermediary variable.

// Callback
<input ref={node => $(node).typehead({ hint: true })} />

// React.createRef
import React, { createRef } from "jsx-dom"

const textbox = createRef()
render(
  <div>
    <label>Username:</label>
    <input ref={textbox} />
  </div>
)

window.onerror = () => {
  textbox.current.focus()
}

// React.useRef
import React, { useRef } from "jsx-dom"

function Component() {
  const textbox = useRef()
  const onClick = () => textbox.current.focus()

  return (
    <div onClick={onClick}>
      <label>Username:</label>
      <input ref={textbox} />
    </div>
  )
}
  1. Rich data jsx properties are accepted, but populated as properties rather than DOM attributes.
class MyCustomElement extends HTMLElement {
  constructor() {
    super();
  }
}
customElements.define('my-custom-element', MyCustomElement);
const richData = { foo: 'bar' }
return <my-custom-element richData={richData} />

Functional and class components

You can write functional and class components and receive passed props in the same way in React. Unlike React, props.children is guaranteed to be an array.

SVG and Namespaces

import React from "jsx-dom"

document.body.appendChild(
  <div class="flag" style={{ display: "flex" }}>
    <h1>Flag of Italy</h1>
    <svg width="150" height="100" viewBox="0 0 3 2" class="flag italy">
      <rect width="1" height="2" x="0" fill="#008d46" />
      <rect width="1" height="2" x="1" fill="#ffffff" />
      <rect width="1" height="2" x="2" fill="#d2232c" />
    </svg>
  </div>
)

Below is a list of SVG tags included.

svg, animate, circle, clipPath, defs, desc, ellipse, feBlend, feColorMatrix, feComponentTransfer, feComposite, feConvolveMatrix, feDiffuseLighting, feDisplacementMap, feDistantLight, feFlood, feFuncA, feFuncB, feFuncG, feFuncR, feGaussianBlur, feImage, feMerge, feMergeNode, feMorphology, feOffset, fePointLight, feSpecularLighting, feSpotLight, feTile, feTurbulence, filter, foreignObject, g, image, line, linearGradient, marker, mask, metadata, path, pattern, polygon, polyline, radialGradient, rect, stop, switch, symbol, text, textPath, tspan, use, view

If you do not need SVG and CSS property automatic type conversion support, you can import from jsx-dom/min for a smaller build.

import React, { SVGNamespace } from "jsx-dom"

function Anchor() {
  return <a namespaceURI={SVGNamespace}>I am an SVG element!</a>
}

If you need to create an SVG element that is not in the list, or you want to specify a custom namespace, use the attribute namespaceURI.

jsx-dom also includes a few utility functions to facilitate the process of refactoring from or to React.

useText

While this is technically not a hook in the React sense, it functions like one and facilitates simple DOM text changes.

import React, { useText } from "jsx-dom"

function Component() {
  const [text, setText] = useText("Downloading")

  fetch("./api").then(() => {
    setText("Done!")
  })

  return (
    <div>Status: {text}</div>
  )
}

useClassList

import React, { useClassList } from "jsx-dom"

function Component() {
  const cls = useClassList(["main", { ready: false }])
  setTimeout(() => {
    cls.add("long-wait")
    cls.toggle("ready")
  }, 2000)

  return (
    <div class={cls}>Status</div>
  )
}

Goodies

Some extra features are provided by this package:

// Returns the event object
export function preventDefault(event: Event): Event;

// Returns the event object
export function stopPropagation(event: Event): Event;

// `namespaceURI` string for SVG Elements.
export const SVGNamespace: string;

// Convert a value into a className string. See docs above.
export function className(value: any): string;

Type aliases for convenience

/** Short type aliases for HTML elements */
export namespace HTML {
    type Anchor = HTMLAnchorElement
    type Button = HTMLButtonElement
    type Div = HTMLDivElement
    ...
}

/** Short type aliases for SVG elements */
export namespace SVG {
    type Anchor = SVGAElement
    type Animate = SVGAnimateElement
    ...
}

API Compatibility with React

The following functions are included for compatibility with React API:

function createFactory(component: string): (props: object) => JSX.Element
function useImperativeHandle<T>(ref: Ref<T>, init: () => T, deps?: DependencyList): void
function useRef<T>(initialValue?: T): RefObject<T>
function forwardRef<T = Node, P = {}>(
  render: (props: P, ref: Ref<T>) => ReactNode
): FunctionComponent<P & { ref?: Ref<T> }>

The following functions do not have memoization or optimization, and are only useful if you are migrating from/to React.

// Returns `render` function
export function memo<P, T extends (props: P) => JSX.Element>(render: T): T;
// Returns `fn` function
export function useMemo<T>(fn: () => T, deps: any[]): T;
// Returns `fn` function
export function useCallback<T extends Function>(fn: T, deps: any[]): T;

export const StrictMode: React.FC;

export class PureComponent {}

Browser Support

There is no support for Internet Explorer.

Known Issues

  • <div />, and other tags, are inferred as a general JSX.Element in TypeScript instead of HTMLDivElement (or the equivalent types). This is a known bug and its fix depends on TypeScript#21699.

  • htm library is not currently compatible with jsx-dom.