Skip to content
Agent Checker
Back to Blog
TechnicalHTMLAI Agents

Web Components and Shadow DOM: The Agent Compatibility Question

Agent Checker3 min read

Web Components let developers build reusable custom elements with encapsulated styles and behaviour. Shadow DOM is the encapsulation mechanism: it creates a separate DOM tree that external JavaScript and CSS cannot reach. This is great for preventing style conflicts, but it creates a real problem for AI agents trying to read your page.

What agents see when they encounter Shadow DOM

Consider a product card built as a web component:

<product-card sku="WK-2045" price="49.99">
  #shadow-root (closed)
    <div class="card">
      <h3>Wireless Keyboard</h3>
      <p class="price">£49.99</p>
      <button>Add to Cart</button>
    </div>
</product-card>

An agent querying the DOM with document.querySelectorAll('h3') will not find the "Wireless Keyboard" heading. It lives inside the shadow root, which is invisible to standard DOM queries. The agent sees <product-card> as an opaque box.

With an open shadow root, agents can access the content via element.shadowRoot, but they need to know to look there. Most agents do not traverse shadow roots by default. With a closed shadow root, even explicit access is blocked.

The scope of the problem

Shadow DOM is still a minority pattern on the web, but its adoption is growing. Design systems from major companies (Google's Material Web, Salesforce's Lightning, Adobe's Spectrum) use web components extensively. If your site uses one of these systems, significant portions of your UI may be hidden inside shadow roots.

The elements most commonly built as web components are exactly the ones agents need to read:

  • Product cards with names, prices, and availability
  • Navigation menus with site structure information
  • Pricing widgets with tier comparisons
  • Form elements with custom inputs and validation
  • Modal dialogues with terms, confirmations, or product details

Why this matters for agents

Agents build their understanding of a page from the DOM structure. When they encounter properly structured HTML, they can extract meaning from headings, links, lists, and semantic elements. Shadow DOM breaks this model. The semantic content exists, but it is in a separate tree that the agent's DOM queries skip over.

An agent trying to compare product prices across your site might find zero products if every product card is a web component with a closed shadow root. The data is there; the agent just cannot reach it.

Strategies for compatibility

Use open shadow roots when possible. Open shadow roots (mode: 'open') allow programmatic access via element.shadowRoot. While most agents do not check shadow roots today, some are starting to, and open mode makes future compatibility possible.

class ProductCard extends HTMLElement {
  constructor() {
    super();
    // Open mode allows external access
    this.attachShadow({ mode: 'open' });
  }
}

Expose key data as attributes on the host element. Even if the shadow DOM content is inaccessible, agents can read attributes on the custom element itself:

<product-card
  name="Wireless Keyboard"
  price="49.99"
  currency="GBP"
  availability="in-stock"
  sku="WK-2045">
</product-card>

This gives agents structured data right on the element, no shadow root traversal needed.

Use slotted content for critical information. Light DOM content projected via <slot> remains accessible to external queries:

<product-card>
  <h3 slot="title">Wireless Keyboard</h3>
  <span slot="price">£49.99</span>
</product-card>

The slotted content lives in the light DOM, so agents can find it with standard queries. The shadow root handles presentation, while the actual data stays accessible.

Supplement with JSON-LD. Regardless of how your components are built, structured data in JSON-LD provides a parallel data source that agents can always read. It does not depend on DOM structure at all.

The practical takeaway

If you are building with web components, assume that agents will not see inside your shadow roots. Expose critical data through element attributes, slotted content, or separate JSON-LD blocks. This costs very little development time and ensures your content is accessible to both human visitors and the agents they send ahead.