TypeScript icon, indicating that this package has built-in type declarations

1.2.4 • Public • Published

Shadow DOM Crawler

This is a zero-dependency script for crawling deeply nested shadow DOMs. This can only crawl shadow structures created with { mode: 'open' } because "closed" structures are inaccessable to JavaScript.

npm install shadow-dom-crawler
yarn add shadow-dom-crawler

Use cases

This library was developed for a very limited set of use cases and should NOT be used to violate the intentions of component developers. Please remember that components use a shadow DOM in order to isolate themselves from the outside world. DO NOT interfere with, modify, or otherwise disrupt the DOMs in 3rd party components. With that said, here are some of the reasons why I built this script:

What NOT to do

  • modify the DOM inside a shadow root
  • share any type of application state between components
  • set properties or attributes on nested components
  • pretty much anything else which is not listed in the use cases above... seriously, don't do it.


findNode(selector: string, startNode?: Node | Node[] | NodeList)

This method is analagous to Element.prototype.querySelector, but works with open shadow DOMs.

Given a valid CSS selector string, will start crawling the document in search of a matching element and will stop crawling as soon as one is found. If no item is found, this will return null. By default this will start crawling at the document.body. You can pass an optional second parameter of Node | Node[] | NodeList from where to start crawling:

import { findNode } from 'shadow-dom-crawler';
const node = findNode('.some-valid-css-selector');
const root = document.getElementById('#root');
const node = findNode('.some .nested .css-selector', root);
const items = document.querySelector('li.items');
const node = findNode('.some complex-css[ selector ]', items);


  • findAll('selector', startNode?) - Find all nodes matching a selector.
  • injectStyles('selector' | node(s), styles, startNode?) - will find all elements matching the selector and inject styles into those elements. One or more elements can optionally be passed in order to skip the crawling step. This will be useful for injecting shared styles into shadow elements.


This uses @stencil/core for testing as it provides convenient wrappers around jest for testing web components. Stencil components are also compiled to standards-compliant components which makes it convenient for creating and nesting multiple components used for testing.

yarn test




Package Sidebar


npm i shadow-dom-crawler

Weekly Downloads






Unpacked Size

15 kB

Total Files


Last publish


  • ryanwheale