Implementation:Puppeteer Puppeteer Injected PierceQuerySelector
| Property | Value |
|---|---|
| sources | packages/puppeteer-core/src/injected/PierceQuerySelector.ts
|
| domains | Injected Scripts, Query Selectors, Shadow DOM |
| last_updated | 2026-02-12 00:00 GMT |
Overview
Description
The PierceQuerySelector module provides in-page query functions that pierce through Shadow DOM boundaries. It exports two functions -- pierceQuerySelector and pierceQuerySelectorAll -- which use document.createTreeWalker to recursively traverse both the light DOM and any attached shadow roots, applying a standard CSS selector match at each step.
Unlike standard querySelector, which stops at shadow boundaries, these functions descend into every ShadowRoot they encounter, making them essential for interacting with Web Components.
Usage
These functions execute inside the browser page context. They are the underlying implementations for the pierce/ query handler in Puppeteer, which is used when selectors are prefixed with the pierce protocol (e.g., page.$('pierce/div.my-class')).
Code Reference
Source Location
packages/puppeteer-core/src/injected/PierceQuerySelector.ts (65 lines)
Signature
export const pierceQuerySelector: (root: Node, selector: string) => Element | null;
export const pierceQuerySelectorAll: (element: Node, selector: string) => Element[];
Import
import { pierceQuerySelector, pierceQuerySelectorAll } from '../injected/PierceQuerySelector.js';
I/O Contract
pierceQuerySelector
| Direction | Name | Type | Description |
|---|---|---|---|
| Input | root | Node |
The root DOM node to begin traversal from; if Document, starts at documentElement
|
| Input | selector | string |
A standard CSS selector string |
| Output | result | null | The first matching element across all shadow boundaries, or null |
pierceQuerySelectorAll
| Direction | Name | Type | Description |
|---|---|---|---|
| Input | element | Node |
The root DOM node to begin traversal from; if Document, starts at documentElement
|
| Input | selector | string |
A standard CSS selector string |
| Output | result | Element[] |
All matching elements across all shadow boundaries |
Usage Examples
import { pierceQuerySelector, pierceQuerySelectorAll } from '../injected/PierceQuerySelector.js';
// Find a single element that may be inside a shadow root
const button = pierceQuerySelector(document, 'button.submit');
if (button) {
button.click();
}
// Find all matching elements across shadow DOM boundaries
const allButtons = pierceQuerySelectorAll(document, 'button.action');
console.log(`Found ${allButtons.length} action buttons across shadow roots`);