Shadow DOM & getShadowRoot

How to reach elements hidden inside web components using Selenium 4's getShadowRoot().

Concept

Modern web apps often use Web Components that hide their internal HTML and CSS inside a Shadow DOM. This makes components reusable and encapsulated — but it also means normal Selenium locators can't see inside them directly.

Shadow DOM Basics

Shadow DOM = a separate DOM tree attached to a normal element.
It gives:
- Encapsulation of styles (CSS doesn't leak in or out).
- Encapsulation of structure (internal markup is hidden behind a boundary).
From Selenium's point of view:
- The page has a host element in the normal DOM.
- Inside that host, there is a shadow root and its own shadow tree.

Shadow DOM Terminology

Shadow Host – The normal DOM element that owns the shadow tree (e.g. <div id="shadow-host">).
Shadow Root – The root node of the shadow tree (#shadow-root (open)).
Shadow Tree – All elements inside the shadow DOM (buttons, inputs, etc.).

Selenium 4 and getShadowRoot()

Before Selenium 4, dealing with Shadow DOM often required workarounds (JavaScript, etc.). Selenium 4 added a direct API: getShadowRoot() is called on a WebElement that is the shadow host. It returns a SearchContext, which you can use like driver to call findElement.

Typical Workflow

Find the shadow host using a normal locator (visible in the regular DOM).
Call getShadowRoot() on that host.
Use the returned shadow root context to search for inner elements.

When to Use It

Use getShadowRoot() when:

You see #shadow-root in DevTools while inspecting an element.
Normal locators like driver.findElement(By.id("shadow-btn")) fail, even though you see the element in DevTools.
You're working with modern frameworks/components that rely on Web Components.

Best Practice Notes

Always separate the two steps clearly: "Find host" → "Cross boundary" → "Find internal element".
Treat each shadow root like a mini-page with its own SearchContext.
Remember: getShadowRoot() works only with open shadow roots (mode: 'open'). Closed shadow roots are not accessible through standard WebDriver.

Interactive Practice

In this lab, you interact with a UI element that lives entirely inside a Shadow DOM.

Shadow Host Element

The button above is inside a Shadow DOM. Try clicking it directly, then use Selenium to interact with it!

What You See on the Page

A card area with:
- Title: "Shadow DOM Content"
- A button labeled: "Click Me (Inside Shadow DOM)"
- A small success message: "✓ Interaction Successful!" (appears after clicking)
Behind the scenes:
- The card is rendered inside a shadow root.
- The host element is in the normal DOM with id="shadow-host"
- Inside the shadow DOM: a wrapper div with class="shadow-card"
- A button with id="shadow-btn"

What's Special for Selenium

That button is not reachable with a simple driver.findElement(By.id("shadow-btn")). Selenium must:

Locate the host by id="shadow-host" in the normal DOM.
Get its shadow root.
Search inside that shadow root for id="shadow-btn".

Java Code Example

ShadowDOMExample.java

1
2
3
4
5
6
7
8
WebElement shadowHost = driver.findElement(By.id("shadow-host"));

SearchContext shadowRoot = shadowHost.getShadowRoot();

WebElement shadowButton = shadowRoot.findElement(By.id("shadow-btn"));
shadowButton.click();

driver.quit();

Code Breakdown

WebElement shadowHost = driver.findElement(By.id("shadow-host"));: Uses a normal locator on the main DOM to find the shadow host element with id="shadow-host".
SearchContext shadowRoot = shadowHost.getShadowRoot();: Calls getShadowRoot() on the host. This crosses the boundary into the shadow DOM and gives you a SearchContext for the shadow root.
WebElement shadowButton = shadowRoot.findElement(By.id("shadow-btn"));: Uses the shadow root context (not driver) to find the internal button with id="shadow-btn". A global driver.findElement(By.id("shadow-btn")) would fail because the button is hidden inside the shadow tree.
shadowButton.click();: Clicks the button inside the Shadow DOM, just like any other WebElement.
driver.quit();: Closes the browser and ends the WebDriver session cleanly.

Pro Tip

Inspect for #shadow-root

Always inspect for #shadow-root in DevTools. If you see it, you know you must use getShadowRoot() to reach inner elements.

Treat as Mini-Page

Think of each shadow root as its own mini-page. Once you have SearchContext shadowRoot, treat it just like driver for that component.

Open vs Closed Shadow Roots

Remember: getShadowRoot() works only for open shadow roots. For closed ones, Selenium cannot access elements by standard APIs — your tests might need to verify behavior indirectly.