hast utility to create trees with ease.

• What is this?
• When should I use this?
• Install
• Use
• API
  • h(selector?[, properties][, …children])
  • s(selector?[, properties][, …children])
• JSX
• Types
• Compatibility
• Security
• Related
• Contribute
• License

This package is a hyperscript interface (like createElement from React and h from Vue and such) to help with creating hast trees.

You can use this utility in your project when you generate hast syntax trees with code. It helps because it replaces most of the repetition otherwise needed in a syntax tree with function calls. It also helps as it improves the attributes you pass by turning them into the form that is required by hast.

You can instead use unist-builder when creating any unist nodes and xastscript when creating xast (XML) nodes.

This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:

npm install hastscript

In Deno with esm.sh:

import {h} from 'https://esm.sh/hastscript@7'

In browsers with esm.sh:

<script type="module">
  import {h} from 'https://esm.sh/hastscript@7?bundle'
</script>

import {h, s} from 'hastscript'

console.log(
  h('.foo#some-id', [
    h('span', 'some text'),
    h('input', {type: 'text', value: 'foo'}),
    h('a.alpha', {class: 'bravo charlie', download: 'download'}, [
      'delta',
      'echo'
    ])
  ])
)

console.log(
  s('svg', {xmlns: 'http://www.w3.org/2000/svg', viewbox: '0 0 500 500'}, [
    s('title', 'SVG `<circle>` element'),
    s('circle', {cx: 120, cy: 120, r: 100})
  ])
)

Yields:

{
  type: 'element',
  tagName: 'div',
  properties: {className: ['foo'], id: 'some-id'},
  children: [
    {
      type: 'element',
      tagName: 'span',
      properties: {},
      children: [{type: 'text', value: 'some text'}]
    },
    {
      type: 'element',
      tagName: 'input',
      properties: {type: 'text', value: 'foo'},
      children: []
    },
    {
      type: 'element',
      tagName: 'a',
      properties: {className: ['alpha', 'bravo', 'charlie'], download: true},
      children: [{type: 'text', value: 'delta'}, {type: 'text', value: 'echo'}]
    }
  ]
}
{
  type: 'element',
  tagName: 'svg',
  properties: {xmlns: 'http://www.w3.org/2000/svg', viewBox: '0 0 500 500'},
  children: [
    {
      type: 'element',
      tagName: 'title',
      properties: {},
      children: [{type: 'text', value: 'SVG `<circle>` element'}]
    },
    {
      type: 'element',
      tagName: 'circle',
      properties: {cx: 120, cy: 120, r: 100},
      children: []
    }
  ]
}

This package exports the identifiers h and s. There is no default export.

The export map supports the automatic JSX runtime. You can pass hastscript/html (or hastscript) or hastscript/svg to your build tool (TypeScript, Babel, SWC) as with an importSource option or similar.

Create virtual hast trees for HTML or SVG.

• h(): root
• h(null[, …children]): root
• h(selector[, properties][, …children]): element

(and the same for s).

Simple CSS selector (string, optional). Can contain a tag name (foo), IDs (#bar), and classes (.baz). If the selector is a string but there is no tag name in it, h defaults to build a div element, and s to a g element. selector is parsed by hast-util-parse-selector. When string, builds an Element. When nullish, builds a Root instead.

Map of properties (Record<string, any>, optional). Keys should match either the HTML attribute name, or the DOM property name, but are case-insensitive. Cannot be given when building a Root.

(Lists of) children (string, number, Node, Array<children>, optional). When strings or numbers are encountered, they are mapped to Text nodes. If Root nodes are given, their children are used instead.

Element or Root.

hastscript can be used with JSX. Either use the automatic runtime set to hastscript/html (or hastscript) or hastscript/svg or import h or s yourself and define it as the pragma (plus set the fragment to null).

The example above can then be written like so, using inline pragmas, so that SVG can be used too:

example-html.jsx:

/** @jsxImportSource hastscript */
console.log(
  <div class="foo" id="some-id">
    <span>some text</span>
    <input type="text" value="foo" />
    <a class="alpha bravo charlie" download>
      deltaecho
    </a>
  </div>
)

example-svg.jsx:

/** @jsxImportSource hastscript/svg */
console.log(
  <svg xmlns="http://www.w3.org/2000/svg" viewbox="0 0 500 500">
    <title>SVG `&lt;circle&gt;` element</title>
    <circle cx={120} cy={120} r={100} />
  </svg>
)

👉 Note: while h supports dots (.) for classes or number signs (#) for IDs in selector, those are not supported in JSX.

You can use estree-util-build-jsx to compile JSX away.

For Babel, use @babel/plugin-transform-react-jsx and either pass pragma: 'h' and pragmaFrag: 'null', or pass importSource: 'hastscript'. This is not perfect as it allows only a single pragma. Alternatively, Babel also lets you configure this with a comment:

/** @jsx s @jsxFrag null */
import {s} from 'hastscript'

console.log(<rect />)

This is useful because it allows using both html and svg when used in different files.

This package is fully typed with TypeScript. It exports the additional types Child and Properties.

Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed.

Use of hastscript can open you up to a cross-site scripting (XSS) attack as values are injected into the syntax tree. The following example shows how a script is injected that runs when loaded in a browser.

const tree = h()

tree.children.push(h('script', 'alert(1)'))

Yields:

<script>alert(1)</script>

The following example shows how an image is injected that fails loading and therefore runs code in a browser.

const tree = h()

// Somehow someone injected these properties instead of an expected `src` and
// `alt`:
const otherProps = {src: 'x', onError: 'alert(2)'}

tree.children.push(h('img', {src: 'default.png', ...otherProps}))

Yields:

<img src="x" onerror="alert(2)">

The following example shows how code can run in a browser because someone stored an object in a database instead of the expected string.

const tree = h()

// Somehow this isn’t the expected `'wooorm'`.
const username = {
  type: 'element',
  tagName: 'script',
  children: [{type: 'text', value: 'alert(3)'}]
}

tree.children.push(h('span.handle', username))

Yields:

<span class="handle"><script>alert(3)</script></span>

Either do not use user input in hastscript or use hast-util-santize.

• unist-builder — create unist trees
• xastscript — create xast trees
• hast-to-hyperscript — turn hast into React, Preact, Vue, etc
• hast-util-from-dom — turn DOM trees into hast
• hast-util-select — querySelector, querySelectorAll, and matches
• hast-util-to-html — turn hast into HTML
• hast-util-to-dom — turn hast into DOM trees

See contributing.md in syntax-tree/.github for started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

MIT © Titus Wormer