hast-util-select

querySelector, querySelectorAll, and matches for HAST nodes.

One notable difference between DOM and HAST is that DOM nodes have references to their parents, meaning that document.body.matches(':last-child') can be evaluated. This information is not stored in HAST, so selectors like that don’t work.

View the list of supported selectors »

Installation

npm:

npm install hast-util-select

API

select.matches(selector, node)

This only checks the element itself, not the surrounding tree. Thus, nesting in selectors is not supported (p b, p > b), neither are selectors like :first-child, etc. This simply checks that the given element matches the selector.

Usage

var h = require('hastscript');
var matches = require('hast-util-select').matches;

matches('b, i', h('b')); //=> true
matches(':any-link', h('a')); //=> false
matches(':any-link', h('a', {href: '#'})); //=> true
matches('.classy', h('a', {className: ['classy']})); //=> true
matches('#id', h('a', {id: 'id'})); //=> true
matches('[lang|=en]', h('a', {lang: 'en'})); //=> true
matches('[lang|=en]', h('a', {lang: 'en-GB'})); //=> true
// ...

Parameters

• node (Node) — Thing to check, could be anything, but should be an element
• selector (string) — CSS selectors (, is also supported)

Returns

boolean — Whether the node matches the selector.

select.select(selector, tree)

Usage

var h = require('hastscript');
var select = require('hast-util-select').select;

console.log(select('h1 ~ :nth-child(even)', h('section', [
  h('p', 'Alpha'),
  h('p', 'Bravo'),
  h('h1', 'Charlie'),
  h('p', 'Delta'),
  h('p', 'Echo')
])));

Yields:

{ type: 'element',
  tagName: 'p',
  properties: {},
  children: [ { type: 'text', value: 'Delta' } ] }

Select the first node matching selector in the given tree (could be the tree itself).

Parameters

• tree (Node) — Thing to search.
• selector (string) — CSS selectors (, is also supported)

Returns

Element? — The found element, if any.

select.selectAll(selector, tree)

Select all nodes matching selector in the given tree (could include the tree itself).

Usage

var h = require('hastscript');
var selectAll = require('hast-util-select').selectAll;

console.log(selectAll('h1 ~ :nth-child(even)', h('section', [
  h('p', 'Alpha'),
  h('p', 'Bravo'),
  h('h1', 'Charlie'),
  h('p', 'Delta'),
  h('p', 'Echo'),
  h('p', 'Foxtrot'),
  h('p', 'Golf')
])));

Yields:

[ { type: 'element',
    tagName: 'p',
    properties: {},
    children: [ { type: 'text', value: 'Delta' } ] },
  { type: 'element',
    tagName: 'p',
    properties: {},
    children: [ { type: 'text', value: 'Foxtrot' } ] } ]

Parameters

• tree (Node) — Thing to search.
• selector (string) — CSS selectors (, is also supported)

Returns

Array.<Element> — All found elements, if any.

Support

• * (universal selector, namespaces not supported)
• , (multiple selector)
• p (type selector)
• .class (class selector)
• #id (id selector)
• [attr] (attribute existence)
• [attr=value] (attribute equality)
• [attr~=value] (attribute contains in space-separated list)
• [attr|=value] (attribute equality or prefix)
• [attr^=value] (attribute begins with)
• [attr$=value] (attribute ends with)
• [attr*=value] (attribute contains)
• :any() (pseudo-class, use :matches instead)
• :matches() (pseudo-class)
• :not() (pseudo-class)
• :any-link (pseudo-class)
• :empty (pseudo-class)
• :blank (pseudo-class)
• :checked (pseudo-class)
• :disabled (pseudo-class)
• :enabled (pseudo-class)
• :optional (pseudo-class)
• :required (pseudo-class)
• article p (combinator: descendant selector)
• article > p (combinator: child selector)
• h1 + p (combinator: adjacent sibling selector)
• h1 ~ p (combinator: general sibling selector)
• * :first-child (pseudo-class)
• * :first-of-type (pseudo-class)
• * :last-child (pseudo-class)
• * :last-of-type (pseudo-class)
• * :nth-child() (pseudo-class)
• * :nth-last-child() (pseudo-class)
• * :nth-last-of-type() (pseudo-class)
• * :nth-of-type() (pseudo-class)
• * :only-child (pseudo-class)
• * :only-of-type (pseudo-class)

Unsupported

• >> (explicit descendant combinator)
• || (column combinator)
• ‡ [attr=value i] (attribute case-insensitive)
• † :active (pseudo-class)
• † :current (pseudo-class)
• † :default (pseudo-class)
• † :defined (pseudo-class)
• § :dir() (pseudo-class)
• † :fullscreen (pseudo-class)
• † :focus (pseudo-class)
• † :future (pseudo-class)
• § :has() (pseudo-class)
• † :hover (pseudo-class)
• † :indeterminate (pseudo-class)
• § :in-range (pseudo-class)
• § :invalid (pseudo-class)
• § :lang() (pseudo-class)
• † :link (pseudo-class)
• † :local-link (pseudo-class)
• † nth-column() (pseudo-class)
• † nth-last-column() (pseudo-class)
• § :out-of-range (pseudo-class)
• † :past (pseudo-class)
• † :paused (pseudo-class)
• † :placeholder-shown (pseudo-class)
• † :playing (pseudo-class)
• § :read-only (pseudo-class)
• § :read-write (pseudo-class)
• § :root (pseudo-class)
• § :scope (pseudo-class)
• † :user-error (pseudo-class)
• † :user-invalid (pseudo-class)
• § :valid (pseudo-class)
• † :visited (pseudo-class)
• † ::before (pseudo-elements: none are supported)

Notes

• * — Not supported in matches.
• † — Needs a user, browser, interactivity, or scripting to make sense
• ‡ — Not supported by the underlying algorithm
• § — Not very interested in writing / including the code for this

License

MIT © Titus Wormer