From 88a94696502bb18160a53f1721a61f309972fc07 Mon Sep 17 00:00:00 2001
From: Jigar Wala <jigarwala007@gmail.com>
Date: Wed, 11 Jan 2023 16:07:50 +0530
Subject: [PATCH] :memo: update readme for dom package

---
 packages/dom/README.md | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/packages/dom/README.md b/packages/dom/README.md
index 8f49b72aa..a160c4f7d 100644
--- a/packages/dom/README.md
+++ b/packages/dom/README.md
@@ -71,7 +71,44 @@ Videos without a `poster` attribute will have the current frame of the video
 serialized into an image and set as the `poster` attribute automatically. This is
 to ensure videos have a stable image to display when screenshots are captured.
 
+### Shadow DOM
+
+Shadow dom  `#shadow-root (open)` is serialized into declarative shadow DOM (`<template shadowroot="open">`) form
+Shadow host element is annotated with special identifier attribute named `data-percy-shadow-host`. This identifier 
+attribute may be used when passing `domTransformation`.
+
 ### Other elements
 
 _All other elements are not serialized._ The resulting cloned document is passed to any provided
 `domTransformation` option before the serialize function returns a DOM string.
+
+
+
+## Examples 
+
+1. perform DOM transformations on serialized DOM 
+
+this example contains scenario of nested shadow DOMs
+
+```js
+import serializeDOM from '@percy/dom';
+
+const domSnapshot = serializeDOM({
+    domTransformation: (documentElement) => {
+      function insertHelloHeader(root) {
+        h1 = document.createElement('h1');
+        h1.innerText = 'Inserted using dom transformations';
+        root.append(h1);
+
+        root.querySelectorAll('[data-percy-shadow-host]')
+          .forEach(
+            shadowHost => {
+              if (shadowHost?.shadowRoot)
+                insertHelloHeader(shadowHost.shadowRoot)
+            });
+
+      }
+      insertHelloHeader(documentElement);
+    }
+  });
+```