How to Handle the Shadow DOM in Selenium

To interact with an element inside a Shadow DOM with Selenium, first find the component’s host in the regular document, get its shadow root with Selenium’s native API, and use that root as the search context. In Python, use host.shadow_root; in JavaScript and Java, call getShadowRoot(). Then locate and interact with descendants through the returned root.

This is Selenium 4’s native approach; JavaScript execution is usually unnecessary when your binding, browser, and driver support the API. The key distinction is that driver.find_element searches the document, while shadow_root.find_element searches inside the component’s root.

1. Find an element in a shadow root with Python

Install Selenium with python -m pip install selenium, start a driver for your browser, and wait for the host to appear before accessing its root:

from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

# Selenium Manager can resolve a compatible driver for common setups.
driver = webdriver.Chrome()
try:
    driver.get("https://example.com")

    wait = WebDriverWait(driver, 10)
    host = wait.until(
        EC.presence_of_element_located((By.CSS_SELECTOR, "my-component"))
    )

    shadow_root = host.shadow_root
    button = shadow_root.find_element(By.CSS_SELECTOR, "button.submit")
    button.click()
finally:
    driver.quit()

Replace my-component and button.submit with selectors from the page. The host is an ordinary document element; the button is searched for inside its shadow root. To collect multiple matches, use shadow_root.find_elements(By.CSS_SELECTOR, "button").

Wait for a descendant, not just the host

A host can exist before its component has attached a root or rendered its content. For components that initialize asynchronously, poll for the descendant and reacquire the root on each attempt:

from selenium.common.exceptions import NoSuchElementException, NoSuchShadowRootException
from selenium.webdriver.support.ui import WebDriverWait


def find_in_shadow(driver, host_selector, child_selector):
    host = driver.find_element(By.CSS_SELECTOR, host_selector)
    root = host.shadow_root
    return root.find_element(By.CSS_SELECTOR, child_selector)

button = WebDriverWait(driver, 10, poll_frequency=0.2).until(
    lambda d: find_in_shadow(d, "my-component", "button.submit")
)
button.click()

If the root is not attached yet, this polling function may raise NoSuchShadowRootException rather than return a value. You can make the retry behavior explicit:

from selenium.common.exceptions import (
    NoSuchElementException,
    NoSuchShadowRootException,
    StaleElementReferenceException,
)


def shadow_button_ready(driver):
    try:
        host = driver.find_element(By.CSS_SELECTOR, "my-component")
        return host.shadow_root.find_element(By.CSS_SELECTOR, "button.submit")
    except (
        NoSuchElementException,
        NoSuchShadowRootException,
        StaleElementReferenceException,
    ):
        return False

button = WebDriverWait(driver, 10, poll_frequency=0.2).until(shadow_button_ready)
button.click()

Keep the retry narrow: catching these exceptions while locating a known component lets the wait handle a transient render. It should not turn unrelated failures into an indefinite wait.

2. Handle nested shadow roots

Each shadow root is a separate search context. If a component inside one root hosts another component, locate the inner host from the outer root, then obtain the inner root:

outer_host = driver.find_element(By.CSS_SELECTOR, "outer-component")
outer_root = outer_host.shadow_root

inner_host = outer_root.find_element(By.CSS_SELECTOR, "inner-component")
inner_root = inner_host.shadow_root

button = inner_root.find_element(By.CSS_SELECTOR, "button.submit")
button.click()

Repeat this host-to-root step for every level. A selector searched from the outer root does not automatically cross into a nested component’s separate shadow root.

3. JavaScript and Java syntax

JavaScript (Node.js)

The JavaScript binding returns a promise from getShadowRoot(), so await it. This runnable example uses the Selenium package and a Chrome driver available to Selenium Manager:

const { Builder, By, until } = require('selenium-webdriver');

(async function () {
  const driver = await new Builder().forBrowser('chrome').build();
  try {
    await driver.get('https://example.com');

    const host = await driver.wait(
      until.elementLocated(By.css('my-component')),
      10000
    );
    const shadowRoot = await host.getShadowRoot();
    const button = await shadowRoot.findElement(By.css('button.submit'));
    await button.click();
  } finally {
    await driver.quit();
  }
})();

Install the binding with npm install selenium-webdriver. In nested components, call getShadowRoot() on each nested host after finding it through its parent root.

Java

In Java, getShadowRoot() returns a SearchContext, which you can use to find descendants:

import org.openqa.selenium.By;
import org.openqa.selenium.SearchContext;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.support.ui.WebDriverWait;
import java.time.Duration;

WebDriver driver = new ChromeDriver();
try {
    driver.get("https://example.com");
    WebElement host = new WebDriverWait(driver, Duration.ofSeconds(10))
        .until(d -> d.findElement(By.cssSelector("my-component")));
    SearchContext shadowRoot = host.getShadowRoot();
    WebElement button = shadowRoot.findElement(By.cssSelector("button.submit"));
    button.click();
} finally {
    driver.quit();
}

Use the syntax for your Selenium language binding: Python’s property access is not the JavaScript or Java method call.

4. What works inside a shadow root

A shadow root is a search context for finding elements. Once located, the returned elements are ordinary WebDriver elements for actions such as clicking, reading text, or sending keys, subject to normal interactability and page state.

Task	Approach
Find one descendant	`root.find_element(By.CSS_SELECTOR, selector)` in Python; the corresponding `findElement` call in other bindings.
Find several descendants	Use `find_elements` or `findElements` on the root.
Find a nested component	Find its host through the current root, then get that host’s shadow root.
Wait for content	Wait for the host and then for the target descendant, retrying transient missing-root or stale-reference states where appropriate.
Click, type, or inspect	Use standard WebElement actions on the element returned by the root search.

Use selectors that identify the component and its intended descendant precisely. If a component rerenders, references to the old host, root, or child may no longer be usable; repeat the lookup from the document.

5. Browser support and protocol behavior

Selenium’s Python WebElement reference documents native shadow-root support from Chromium 96, Firefox 96, and Safari 16.4. Treat these as the documented thresholds for that reference, not as a guarantee for every Selenium binding, browser build, or driver combination. Check the actual versions in your test environment and verify the same flow in each supported browser.

WebDriver has dedicated protocol references and commands for shadow roots. A JavaScript execute_script workaround is therefore not the default when the native API is available. The W3C WebDriver specification cited here is a Working Draft dated 2026-05-28, so its protocol description should not be mistaken for a finalized recommendation.

6. Troubleshooting

Symptom	Likely cause	Fix
`NoSuchElementException` when finding the host	The host selector is wrong, the page has not navigated or rendered yet, or the element is in another frame.	Check the selector in the regular document, wait for the host, and switch to the correct frame before locating it.
`NoSuchShadowRootException` / no shadow root	The located element is not the actual host, or the component has not attached its root yet.	Inspect the component structure, confirm the host selector, and wait for component readiness. A light-DOM wrapper around the component may not itself own the root.
`DetachedShadowRootException` or stale element reference	A rerender, navigation, or DOM replacement detached the old host/root.	Reacquire the host from the current document and get a fresh root and child. Do not keep root references across page transitions or component rerenders.
Root lookup works but child lookup fails	The child selector is incorrect, the child has not rendered, or the target is in a deeper nested root.	Check the selector and component readiness; traverse each nested host and root one level at a time.
Works in one browser but not another	Browser, driver, or binding versions differ, or one environment predates the documented support threshold.	Record and compare browser, driver, and Selenium versions; update compatible components and run the same small lookup in the full test matrix.
Element found but click fails	The element may be hidden, covered, disabled, or not yet interactable.	Wait for the relevant state, confirm the correct element was found, and use normal WebDriver interaction checks. Shadow-root lookup does not bypass interactability rules.

7. Reliability, performance, and cost

Native shadow-root calls avoid hand-written JavaScript traversal and use WebDriver’s shadow-root protocol. Each lookup still involves browser automation commands, so keep selectors specific and avoid repeatedly traversing a stable component tree inside tight loops. Prefer explicit waits for the state you need over fixed long sleeps.

For reliable tests, reacquire references after navigation or rerendering, make readiness conditions match the component’s behavior, and test against the browser and driver versions used in deployment. A missing root is a component lifecycle or host-selection issue; a detached root means the old reference no longer points to the active document.

Running Selenium has the ordinary costs of browser and test infrastructure: compute, browser startup, concurrency, and the maintenance of drivers and test environments. This API technique itself has no separate Selenium fee; infrastructure and any hosted browser service are priced separately according to what you use.

8. Or skip the browser setup

If your goal is a screenshot of a page rather than interacting with its shadow DOM, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. One request returns a PNG, JPEG, WebP, or PDF. It is not a replacement for Selenium interaction with elements inside a shadow root.

cURL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for request options. Cookie banners are accepted and removed before capture, along with known newsletter popups and chat widgets; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. An MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month, with no card required.

9. FAQ

Can Selenium access a shadow root without JavaScript?

Yes, when your Selenium binding and browser support the native API. Get the root from the host and search through it.

Why can’t a normal CSS selector find the shadow DOM child?

A document-level lookup does not search inside a shadow root. First locate the host, then search from its root.

Should I use JavaScript to pierce the shadow boundary?

Use the native API when it is supported. It is Selenium’s direct shadow-root search path and avoids making script execution your default workaround.

Can I use XPath inside a shadow root?

The root is a search context, but selector support depends on the locator strategy and binding. CSS selectors are a straightforward choice for the examples here; check your binding’s locator documentation if you need another strategy.