Skip to content

Shadow DOM

James Conway edited this page Nov 19, 2026 · 1 revision

A page can carry shadow trees in its HTML: a <template shadowrootmode="open"> inside an element becomes that element's shadow root as the page is parsed, the way every major browser now does. Parsec attaches them the same way, so a web component's markup, its slots and the styles scoped to it are in the tree you get back, not lost in an inert template.

use parsec::css::SelectorList;

let html = r#"<user-card><template shadowrootmode="open"><style>:host { display: block }</style><b><slot name="who"></slot></b></template><span slot="who">Ada</span></user-card>"#;
let doc = parsec::parse(html, false);
let host = SelectorList::parse("user-card").unwrap().select_first(&doc, doc.root()).unwrap();
let root = doc.shadow_root(host).unwrap();

// The document's own queries don't enter the shadow tree; the root's do.
assert!(SelectorList::parse("b").unwrap().select_first(&doc, doc.root()).is_none());
let slot = SelectorList::parse("slot").unwrap().select_first(&doc, root).unwrap();

// The light-DOM <span> is assigned to the slot by name.
let span = doc.assigned_nodes(slot)[0];
assert_eq!(doc.text(span), "Ada");

How the parser attaches one

It follows the HTML Standard's steps for a template start tag in the "in head" insertion mode. A <template> with a valid shadowrootmode (open or closed) becomes the parent element's shadow root, with shadowrootdelegatesfocus, shadowrootclonable, shadowrootserializable and shadowrootslotassignment read as the standard says. It stays an ordinary template when the parent can't be a shadow host (only certain elements and custom elements can), already has a shadow root, or is the <html> element, or when the mode isn't valid.

Options::declarative_shadow_roots controls it. Left as None it does what the standard does: on for a whole document, off for a fragment, the way innerHTML ignores them. Some(true) turns them on for a fragment too, as setHTMLUnsafe does. One difference for fragments: the context element is never made a host, since it isn't part of the result.

Reading and walking shadow trees

  • shadow_root(host) and shadow_host(root) go between a host and its root. A shadow root's Kind is ShadowRoot, with its mode and flags.
  • The ordinary tree walks (children, select from the document, outer_html) stay out of shadow trees, as the DOM's do. Start from the root to go in.
  • Slots: assigned_nodes(slot), flattened_assigned_nodes(slot) and assigned_slot(node), for named and default slots and for manual assignment with assign.
  • The flat tree, what a browser would render: flat_children, flat_parent and flat_tree.
  • attach_shadow(host, init) attaches one by hand, with the DOM's rules; EditError::NotAShadowHost says the element can't take one.

Selectors inside a shadow tree

:host, :host(<compound>), :host-context(<compound>) and ::slotted(<compound>) work, from CSS Scoping. They match only in a shadow tree's own scope: run select from a shadow root, or matches with the root as scope. There the host stands in for the root, with no features of its own. The arguments are compound selectors only, so :host(:not(.a .b)) is refused.

Writing it back out

outer_html and inner_html leave shadow roots out, as innerHTML does. SerializeOptions { serializable_shadow_roots: true, .. } writes the ones marked serializable, and shadow_roots lists any others to include, which is getHTML(). See Serialization.

XPath and editing

XPath leaves shadow trees out, like document.evaluate; index a shadow root as a root of its own to query inside it (XPath). A shadow root can't be inserted anywhere, a host can't be moved into its own shadow tree, and a host keeps its shadow root when it's moved or renamed.

Conformance

The static cases of web-platform-tests' shadow-dom/declarative suite run in cargo test: 7,590 passed, 0 failed. They cover the tree cases, attaching to every element, getHTML with every combination of options, slot-assignment serialization and attribute order. WPT's :host selector cases now run too (Conformance). Lexbor has a shadow root node type, but its parser never attaches one.

Clone this wiki locally