Skip to content

docs: add warning about rem unit inheritance in Shadow Root UI #2330

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Aniket-lodh wants to merge 7 commits into
base: main
Choose a base branch
from
+41 −0
Open

docs: add warning about rem unit inheritance in Shadow Root UI #2330

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
074d7ad
docs: add warning about rem unit inheritance in Shadow Root UI
Aniket-lodh May 2, 2026
c4ef653
Update docs/guide/essentials/content-scripts.md
Aniket-lodh May 7, 2026
92afe78
Update docs/guide/essentials/content-scripts.md
Aniket-lodh May 7, 2026
6666def
Update docs/guide/essentials/content-scripts.md
Aniket-lodh May 7, 2026
b776fe8
Update docs/guide/essentials/content-scripts.md
Aniket-lodh May 7, 2026
468dfbd
Update docs/guide/resources/faq.md
Aniket-lodh May 7, 2026
7a94f07
docs: use GitHub alert syntax and fix warning block structure
Aniket-lodh May 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions docs/guide/essentials/content-scripts.md
View file
Open in desktop
Comment thread
Aniket-lodh marked this conversation as resolved.
Copy link
Copy Markdown
Collaborator

@PatrykKuniczak PatrykKuniczak May 7, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can't set text next to [!WARNING[.
Like smah mentioned here:
https://github.com//pull/2336#issuecomment-4394097768

Let's see how it looks on github.
https://github.com/Aniket-lodh/wxt/blob/7a94f07344d67c6e5321c73aabca0ebaf3020a1c/docs/guide/essentials/content-scripts.md

Let's check it next time, if everything is OK, before you'll request any review.
You're almost there 😄

Original file line number Diff line number Diff line change
Expand Up @@ -449,6 +449,40 @@ Full examples:
- [react-content-script-ui](https://github.com/wxt-dev/examples/tree/main/examples/react-content-script-ui)
- [tailwindcss](https://github.com/wxt-dev/examples/tree/main/examples/tailwindcss)

> [!WARNING] `rem` Units Are Not Fully Isolated
> While `createShadowRootUi` isolates most CSS, **`rem` units aren't isolated** inside the Shadow DOM. That's because `rem` is relative to the root `<html>` element's `font-size`, which lives _outside_ the Shadow Root.
> Property `all: initial` **doesn't** affect how `rem` values.
>
> This affects any CSS framework that uses `rem` units by default, including **Tailwind CSS**.
>
> **Fix: Convert `rem` to `px` at build time**
>
> Use [`postcss-rem-to-responsive-pixel`](https://www.npmjs.com/package/postcss-rem-to-responsive-pixel) to automatically convert `rem` units to `px` during the build, eliminating the dependency on the host page's root font-size.
>
> 1. Install the package:
>
> ```sh
> bun i -D postcss-rem-to-responsive-pixel
> ```
>
> 2. Configure your PostCSS config:
>
> ```js [postcss.config.mjs]
> import postcssRemToResponsivePx from 'postcss-rem-to-responsive-pixel';
>
> export default {
> plugins: [
> postcssRemToResponsivePx({
> rootValue: 16,
> propList: ['*'],
> transformUnit: 'px',
> }),
> ],
> };
> ```
>
> See [Issue #678](https://github.com/wxt-dev/wxt/issues/678) for additional context on this behavior.

### IFrame

If you don't need to run your UI in the same frame as the content script, you can use an IFrame to host your UI instead. Since an IFrame just hosts an HTML page, **_HMR is supported_**.
Expand Down
7 changes: 7 additions & 0 deletions docs/guide/resources/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,13 @@ Both issues have the same cause: the library puts something outside the `ShadowR

Both issues have the same fix: tell the library to put elements inside the `ShadowRoot`, not outside it. See the details above for more information and example fixes for each problem.

## My content script UI looks different on certain websites

If your `createShadowRootUi` looks correct on most sites but appears at the wrong size on others (e.g., Reddit),
That's because `rem` unit is relative to the `<html>` element's `font-size`, which lives outside the Shadow DOM. When a website overrides it, your UI scales incorrectly.

The fix is to convert `rem` units to `px` at build time using a PostCSS plugin. See the [Shadow Root section in Content Scripts](/guide/essentials/content-scripts#shadow-root) for the full solution.

## Does WXT provide docs for LLMs?

Yes, WXT's documentation provides markdown files based on the [the /llms.txt proposal](https://llmstxt.org/).
Expand Down