readme.md

hast-util-from-selector

hast utility to create nodes from a complex CSS selectors.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • fromSelector(selector?[, options])
  • Options
  • Space
• Support
• Types
• Compatibility
• Security
• Related
• Contribute
• License

What is this?

This package is a utility that can generate elements from complex CSS selectors.

When should I use this?

You can use this when you’re generating a bunch of elements, and manually creating objects each time is starting to feel like a waste. This package is much more powerful than hast-util-parse-selector, and similar to hastscript.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install hast-util-from-selector

In Deno with esm.sh:

import {fromSelector} from 'https://esm.sh/hast-util-from-selector@3'

In browsers with esm.sh:

<script type="module">
  import {fromSelector} from 'https://esm.sh/hast-util-from-selector@3?bundle'
</script>

Use

import {fromSelector} from 'hast-util-from-selector'

console.log(fromSelector('p svg[viewbox="0 0 10 10"] circle[cx=10][cy=10][r=10]'))

Yields:

{
  type: 'element',
  tagName: 'p',
  properties: {},
  children: [
    {
      type: 'element',
      tagName: 'svg',
      properties: {viewBox: '0 0 10 10'},
      children: [
        {
          type: 'element',
          tagName: 'circle',
          properties: {cx: '10', cy: '10', r: '10'},
          children: []
        }
      ]
    }
  ]
}

API

This package exports the identifier fromSelector. There is no default export.

fromSelector(selector?[, options])

Create one or more Elements from a CSS selector.

Parameters

• selector (string, default: '') — CSS selector
• options (Options, optional) — configuration

Returns

Element.

Options

Configuration (TypeScript type).

Fields

• space (Space, default: 'html') — which space first element in the selector is in. When an svg element is created in HTML, the space is automatically switched to SVG

Space

Name of namespace (TypeScript type).

Type

type Space = 'html' | 'svg'

Support

• * (universal selector, creates a div in HTML, g in SVG)
• p (type selector)
• .class (class selector)
• #id (id selector)
• [attr] (attribute existence, creates a boolean)
• [attr=value] (attribute equality)
• article p (descendant combinator)
• article > p (child combinator)
• section h1 + p (next-sibling combinator, not at root)
• section h1 ~ p (subsequent-sibling combinator, not at root)

Types

This package is fully typed with TypeScript. It exports the additional types Options and Space.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, hast-util-from-selector@^3, compatible with Node.js 16.

Security

Use of hast-util-from-selector can open you up to a cross-site scripting (XSS) attack as values are injected into the syntax tree.

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

Related

• hast-util-parse-selector — create an element from a simple CSS selector

Contribute

See contributing.md in syntax-tree/.github for ways to get 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.

License

MIT © Titus Wormer