diff --git a/bun.lock b/bun.lock
index a268fbd5..86d3e0d5 100644
--- a/bun.lock
+++ b/bun.lock
@@ -296,7 +296,7 @@
"@1natsu/wait-element": "^4.1.2",
"@aklinker1/rollup-plugin-visualizer": "5.12.0",
"@webext-core/fake-browser": "^1.3.4",
- "@webext-core/isolated-element": "^1.1.3",
+ "@webext-core/isolated-element": "^3.0.0",
"@webext-core/match-patterns": "^1.0.3",
"@wxt-dev/browser": "workspace:^",
"@wxt-dev/storage": "workspace:^1.0.0",
@@ -1243,7 +1243,7 @@
"@webext-core/fake-browser": ["@webext-core/fake-browser@1.3.4", "", { "dependencies": { "lodash.merge": "^4.6.2" } }, "sha512-nZcVWr3JpwpS5E6hKpbAwAMBM/AXZShnfW0F76udW8oLd6Kv0nbW6vFS07md4Na/0ntQonk3hFnlQYGYBAlTrA=="],
- "@webext-core/isolated-element": ["@webext-core/isolated-element@1.1.4", "", { "dependencies": { "is-potential-custom-element-name": "^1.0.1" } }, "sha512-JXF0F3b9JvSFmgrZ9fiaR1kiRZHXCSvwSctdahzIDmZXk2eq5H1Qev/Xk2wo3FxuwHPbdkcqDqvAowGZKLR9Ew=="],
+ "@webext-core/isolated-element": ["@webext-core/isolated-element@3.0.0", "", { "dependencies": { "is-potential-custom-element-name": "^1.0.1" } }, "sha512-PmSIBMSe+rFw6eXzpJoV+glc1HPO40clcT9FJ7rSfCQzNewK8/nQZoBYWen2cMqdXdBNM9to/IbNNu5mdQLaPg=="],
"@webext-core/match-patterns": ["@webext-core/match-patterns@1.0.3", "", {}, "sha512-NY39ACqCxdKBmHgw361M9pfJma8e4AZo20w9AY+5ZjIj1W2dvXC8J31G5fjfOGbulW9w4WKpT8fPooi0mLkn9A=="],
diff --git a/docs/guide/resources/upgrading.md b/docs/guide/resources/upgrading.md
index 8e89ee9a..356def92 100644
--- a/docs/guide/resources/upgrading.md
+++ b/docs/guide/resources/upgrading.md
@@ -64,6 +64,43 @@ In v0.20, how automatic startup is enabled/disabled has changed:
rm ~/web-ext.config.ts
```
+## Shadow root UIs no longer include a full HTML document
+
+`@webext-core/isolated-element` was upgraded to v2. This release changes the internal structure of the shadow DOM, simplifying it from a full `` document to just a `div`:
+
+:::code-group
+
+```[Before]
+
+
+
+
+
+ ...your app
+
+
+```
+
+```[After]
+
+
+ ...your app
+
+```
+
+:::
+
+Most modern CSS frameworks support the simplified "fragment", but if yours doesn't, please open an issue. You'll know if something broke because your content script UI will be unstyled.
+
+If you roll your own CSS, make sure your base styles are applied to shadow root hosts like so:
+
+```css
+:root { /* [!code --] */
+:root, :host { /* [!code ++] */
+ /* base styles... */
+}
+```
+
## New Deprecations in v0.20
Deprecated APIs will be removed in the next major release.
diff --git a/packages/wxt/package.json b/packages/wxt/package.json
index 164a1481..5d904d0c 100644
--- a/packages/wxt/package.json
+++ b/packages/wxt/package.json
@@ -19,7 +19,7 @@
"@1natsu/wait-element": "^4.1.2",
"@aklinker1/rollup-plugin-visualizer": "5.12.0",
"@webext-core/fake-browser": "^1.3.4",
- "@webext-core/isolated-element": "^1.1.3",
+ "@webext-core/isolated-element": "^3.0.0",
"@webext-core/match-patterns": "^1.0.3",
"@wxt-dev/browser": "workspace:^",
"@wxt-dev/storage": "workspace:^1.0.0",
diff --git a/packages/wxt/src/utils/content-script-ui/shadow-root.ts b/packages/wxt/src/utils/content-script-ui/shadow-root.ts
index db92e755..c10cbdcd 100644
--- a/packages/wxt/src/utils/content-script-ui/shadow-root.ts
+++ b/packages/wxt/src/utils/content-script-ui/shadow-root.ts
@@ -55,7 +55,7 @@ export async function createShadowRootUi(
const mount = () => {
// Add shadow root element to DOM
mountUi(shadowHost, options);
- applyPosition(shadowHost, shadow.querySelector('html'), options);
+ applyPosition(shadowHost, uiContainer, options);
// Add document CSS
if (