Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/alex-kinokon/jsx-dom
Use JSX to create DOM elements.
https://github.com/alex-kinokon/jsx-dom
dom javascript jsx styled-components typescript
Last synced: 25 days ago
JSON representation
Use JSX to create DOM elements.
- Host: GitHub
- URL: https://github.com/alex-kinokon/jsx-dom
- Owner: alex-kinokon
- License: bsd-3-clause
- Created: 2016-10-24T22:08:57.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2024-04-03T18:11:21.000Z (7 months ago)
- Last Synced: 2024-05-10T02:41:32.113Z (6 months ago)
- Topics: dom, javascript, jsx, styled-components, typescript
- Language: TypeScript
- Homepage:
- Size: 1.27 MB
- Stars: 269
- Watchers: 5
- Forks: 29
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-jsx - jsx-dom
README
# jsx-dom
[](https://opensource.org/licenses/BSD-3-Clause)
[](https://travis-ci.org/proteriax/jsx-dom)
[](https://badge.fury.io/js/jsx-dom)
Use JSX for creating DOM elements. Supports ES Module and TypeScript.
**NEW!** [Styled components are now supported.](#styled-components)
## Installation
```bash
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](https://babeljs.io/docs/en/babel-plugin-transform-react-jsx), simply set `jsxImportSource` to `jsx-dom` or `jsx-dom/min` and you can omit the import.
```jsx
import React from "jsx-dom"
// DOM Elements.
document.body.appendChild(
Hello World
)
// Functional components
// `defaultProps` and `props.children` are supported natively and work as you expect.
function Hello(props) {
return (
Hello, {props.firstName} {props.lastName}!
)
}
Hello.defaultProps = {
firstName: "John",
}
document.body.appendChild()
// 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 (
Welcome, {this.props.firstName} {this.props.lastName}!
)
}
}
document.body.appendChild()
```
### Styled Components
```tsx
import { styled } from "jsx-dom"
const HeaderText = styled.h2`
font-size: 20px;
font-weight: 500;
`
document.body.appendChild(
Welcome!
)
const Name = styled.div<{ large?: boolean }>`
font-size: ${props => props.large ? 40 : 20}px;
${props => props.large ? "font-weight: 600;" : ""}
`
document.body.appendChild(
Welcome!
)
```
### Shadow DOM
```tsx
import { ShadowRoot } from "jsx-dom"
document.body.appendChild(
:root { font-family: Helvetica Neue; }
Hello
)
```
## 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](https://facebook.github.io/react/docs/jsx-in-depth.html#booleans-null-and-undefined-are-ignored), and everything else will be used. For example,
```jsx
```
### 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.
```jsx
```
### 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.
```jsx
```
### Other Attributes
1. `dataset` accepts an object, where keys with a `null` or `undefined` value will be ignored.
```jsx
```
2. 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 = ...`).
```jsx
e.preventDefault()} />
```
3. `innerHTML`, `innerText` and `textContent` are accepted.
4. `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](https://reactjs.org/docs/react-api.html#reactcreateref). This is useful when you have a nested node tree and need to access a node inside without creating an intermediary variable.
```jsx
// Callback
$(node).typehead({ hint: true })} />
// React.createRef
import React, { createRef } from "jsx-dom"
const textbox = createRef()
render(
Username:
)
window.onerror = () => {
textbox.current.focus()
}
// React.useRef
import React, { useRef } from "jsx-dom"
function Component() {
const textbox = useRef()
const onClick = () => textbox.current.focus()
return (
Username:
)
}
```
5. Rich data jsx properties are accepted, but populated as properties rather than DOM attributes.
```jsx
class MyCustomElement extends HTMLElement {
constructor() {
super();
}
}
customElements.define('my-custom-element', MyCustomElement);
const richData = { foo: 'bar' }
return
```
### 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
```jsx
import React from "jsx-dom"
document.body.appendChild(
Flag of Italy
)
```
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.
```jsx
import React, { SVGNamespace } from "jsx-dom"
function Anchor() {
return I am an SVG element!
}
```
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.
```jsx
import React, { useText } from "jsx-dom"
function Component() {
const [text, setText] = useText("Downloading")
fetch("./api").then(() => {
setText("Done!")
})
return (
Status: {text}
)
}
```
## `useClassList`
```jsx
import React, { useClassList } from "jsx-dom"
function Component() {
const cls = useClassList(["main", { ready: false }])
setTimeout(() => {
cls.add("long-wait")
cls.toggle("ready")
}, 2000)
return (
Status
)
}
```
## Goodies
Some extra features are provided by this package:
```ts
// 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
```ts
/** 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:
```ts
function createFactory(component: string): (props: object) => JSX.Element
function useImperativeHandle(ref: Ref, init: () => T, deps?: DependencyList): void
function useRef(initialValue?: T): RefObject
function forwardRef(
render: (props: P, ref: Ref) => ReactNode
): FunctionComponent
}>
```
The following functions do **not** have memoization or optimization, and are only useful if you are
migrating from/to React.
```ts
// Returns `render` function
export function memo
JSX.Element>(render: T): T;
// Returns `fn` function
export function useMemo(fn: () => T, deps: any[]): T;
// Returns `fn` function
export function useCallback(fn: T, deps: any[]): T;
export const StrictMode: React.FC;
export class PureComponent {}
```
## Browser Support
There is no support for Internet Explorer.
## Known Issues
* `
`, 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](https://github.com/Microsoft/TypeScript/issues/21699).
* [htm](https://github.com/developit/htm) library is [not currently compatible](https://github.com/proteriax/jsx-dom/issues/32) with jsx-dom.