Solving Style Conflicts with Shadow DOM

What this post covers >>

• A brief explanation of what Shadow DOM is
• How it was actually applied and troubleshooting

1. Introduction

Gachon Tools is a Chrome extension that renders on top of the university's LMS (Learning Management System). I wrote about this project in detail in a previous post, Building a Chrome Extension with React.

While working on this project, there was one major problem: style conflicts with the LMS's global styles!

Looking at the code from that time, you can see the desperate struggle to overcome style conflicts when using Chakra UI's Tab component.. 😢

<Tab
  key={tab}
  position="relative"
  fontSize="14px"
  borderRadius="none"
  border="none"
  outline="none !important"
  _hover={{
    _dark: { bg: 'blue.800', color: 'white' },
  }}
  _focus={{ outline: 'none', bg: 'none', border: 'none' }}
  _active={{ outline: 'none', bg: 'none' }}
  _light={{ color: 'gray.700', _selected: { color: 'blue.600' } }}
  _dark={{ color: 'gray.200', _selected: { color: 'blue.400' } }}
  _selected={{ color: 'blue.600', borderBottom: '2px solid' }}
>
  {tab}
</Tab>

This kind of style overriding made maintenance extremely difficult. And this approach couldn't perfectly resolve all style conflicts.

Some of the LMS global styles

Previously, we used JavaScript's createElement method to create DOM elements and inject them directly into the LMS page.
However, this approach caused conflicts with the LMS's global styles, requiring complex style overrides to resolve them. As a result, we had to invest significant time in styling.

To solve this problem, we adopted Shadow DOM, a web standard technology. Shadow DOM creates an independent DOM tree that encapsulates styles, effectively preventing conflicts with external styles.

In this post, I'll briefly cover Shadow DOM and introduce the process of applying it in Gachon Tools. I'll also share the challenges encountered during the process and how they were resolved, hoping to provide practical help to developers facing similar issues.

2. Understanding Shadow DOM

2.1. What is Shadow DOM?

When building web pages, you frequently encounter elements with complex structures and styles. Building these from scratch every time is inefficient, and conflicts with the existing page are always a concern. This is where Shadow DOM comes in.

Shadow DOM is a technology for creating an independent DOM tree within a web page. This DOM tree is separated from the main document's DOM and has its own scope. This enables encapsulation of styles and functionality, allowing it to operate independently without being affected by external influences.

In fact, commonly used HTML elements like <video>, <audio>, and <input type="date"> internally use Shadow DOM. These elements have complex internal structures, but thanks to Shadow DOM, they can be easily used with a single simple tag.

Naver's search input

As such, Shadow DOM allows complex components to be used simply while also being a powerful tool for resolving style conflicts. As one of the core technologies that compose Web Components, it greatly improves modularity and reusability in web development.

2.2. Structure of Shadow DOM

The structure of Shadow DOM consists of the following key elements:

1. Shadow host: The regular DOM element to which the Shadow DOM is attached
2. Shadow tree: The DOM tree inside the Shadow DOM
3. Shadow boundary: The boundary between the Shadow DOM and the regular DOM
4. Shadow root: The root node of the Shadow tree

https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM

Through this structure, Shadow DOM forms an independent DOM tree separated from the outside, achieving encapsulation of styles and functionality.

Here is a simple example of creating a Shadow DOM:

// Select the element to create Shadow DOM on
const host = document.querySelector('#host')

// Create Shadow DOM
const shadowRoot = host.attachShadow({ mode: 'open' })

// Add content to Shadow DOM
shadowRoot.innerHTML = `
  <style>
    p { color: red; }
  </style>
  <p>This text is inside the Shadow DOM.</p>
`

This code creates a Shadow DOM and adds styles and content inside it. The Shadow DOM created this way becomes an independent component unaffected by external styles.

2.2. Pros and Cons of Shadow DOM

Shadow DOM provides powerful features, but it's not a suitable solution for every situation.
Therefore, it's important to understand the pros and cons well and decide whether to use Shadow DOM based on your project's characteristics and requirements.

Pros

• Style isolation: Predictable styling is possible without being affected by external styles.
• Encapsulation: A cleaner DOM can be maintained by hiding the internal structure of components.
• Scope limitation: Prevents conflicts by limiting the scope of JavaScript and CSS.
• Performance optimization: The browser can apply styles more efficiently.

Cons

• Learning curve: New concepts and APIs need to be learned.
• Debugging difficulty: Debugging can be complex as the internal structure of Shadow DOM is hidden.
• Difficulty applying external styles: It's hard to apply global styles inside Shadow DOM.
• Browser support: Not supported in some older browsers.

For more details on Shadow DOM, please refer to the resources below.

• TOAST UI: Web Components (3) - Shadow DOM
• MDN: Using shadow DOM

3. Applying Shadow DOM (Gachon Tools)

We've covered the concept and structure of Shadow DOM. Now let's look at how it was applied in the Gachon Tools Chrome extension.

3.1. Project Overview

The Gachon Tools project is a Chrome extension developed using Vite and @crxjs/vite-plugin. During development, the Shadow DOM implementation approach also changed as the project migrated from Chakra UI to Tailwind CSS. Let's look at each approach to see how Shadow DOM is actually used.

3.2. With Chakra UI + Emotion

Initially, we used Chakra UI and Emotion, implementing Shadow DOM with the react-shadow library.

import { PropsWithChildren } from 'react'
import createCache from '@emotion/cache'
import { CacheProvider, EmotionCache } from '@emotion/react'
import { useEffect, useRef, useState } from 'react'
import root from 'react-shadow/emotion'

export function ShadowRootWrapper({ children }: PropsWithChildren) {
  const shadowRef = useRef<HTMLElement>(null)

  const [emotionCache, setEmotionCache] = useState<EmotionCache | null>(null)

  useEffect(() => {
    if (!shadowRef.current?.shadowRoot) return

    const cache = createCache({
      key: 'shadow',
      container: shadowRef.current.shadowRoot,
    })

    setEmotionCache(cache)
  }, [])

  return (
    <root.div ref={shadowRef}>
      <CacheProvider value={emotionCache}>{emotionCache ? children : null}</CacheProvider>
    </root.div>
  )
}

This code creates a Shadow DOM using react-shadow/emotion and injects styles through Emotion's CacheProvider.

To use Chakra UI within a Shadow DOM, the ChakraProvider needs to be configured as follows:

import {PropsWithChildren} from 'react' import {ChakraProvider} from '@chakra-ui/react'

import { ShadowRootWrapper } from './ShadowRootWrapper'
import { customTheme } from '@/constants/customTheme'

export function ShadowChakraProvider({ children }: PropsWithChildren) {
 return (
   <ShadowRootWrapper>
     <ChakraProvider cssVarsRoot=":host,:root" theme={customTheme}> // 👈
       {children}
     </ChakraProvider>
   </ShadowRootWrapper>
 )
}

According to this documentation, the cssVarsRoot property allows you to specify which element CSS variables should be attached to.

Here, cssVarsRoot=":host,:root" configures Chakra UI's CSS variables to be applied to both the Shadow DOM's :host and the regular DOM's :root. This allows the same style variables to be used both inside and outside the Shadow DOM.

3.3. With Tailwind CSS

After migrating to Tailwind CSS, we switched to implementing Shadow DOM directly.

import { SHADOW_HOST_ID } from '@/constants'

export default function createShadowRoot(): ShadowRoot {
  const host = document.createElement('div')
  host.setAttribute('id', SHADOW_HOST_ID)
  const shadowRoot = host.attachShadow({ mode: 'open' })
  document.body.appendChild(host)

  return shadowRoot
}

This approach directly implements the basic structure of Shadow DOM described earlier. The createShadowRoot function creates a Shadow host, attaches a Shadow root to it, and then adds it to the document. Through this function, Shadow DOM can be easily created and used anywhere in the project.

4. Troubleshooting

During the process of applying Shadow DOM, we encountered issues with CSS injection in the development environment and applying external library styles. We tried various methods to resolve these.

4.1. CSS Injection Issue in Development Environment

Problem

CSS was not being properly injected into the Shadow DOM in the development environment. In particular, import "index.css" was not working as expected during Hot Module Replacement (HMR).

Root Cause Analysis

According to this issue, import "index.css" may not work properly during HMR.

1. Normally, import "index.css" automatically injects styles into document.head.
2. When using Tailwind CSS, the index.css file is not directly modified, so HMR is not properly triggered.

Solution

To solve this problem, we added special logic that only runs in the development environment.

import { SHADOW_HOST_ID } from '@/constants'

const isDev = import.meta.env.MODE === 'development'

export default function createShadowRoot(): ShadowRoot {
  const host = document.createElement('div')
  host.setAttribute('id', SHADOW_HOST_ID)
  const shadowRoot = host.attachShadow({ mode: 'open' })

  // 👇
  if (isDev) {
    const styleElement = document.querySelector('style[data-vite-dev-id]')

    if (styleElement) {
      shadowRoot.appendChild(styleElement)
    }
  }

  document.body.appendChild(host)

  return shadowRoot
}

This code finds the style element generated by Vite (style[data-vite-dev-id]) in the development environment and injects it directly into the Shadow DOM. This confirmed that styles are properly applied even during HMR.

4.2. External Library Style Application Issue

Problem

When using the react-easy-crop library, its styles were not being applied inside the Shadow DOM.

Root Cause Analysis

Upon inspection with developer tools, the library's CSS was being injected into document.head. Since Shadow DOM does not inherit external styles, these styles were not being applied inside the Shadow DOM.

Solution

We used an approach of importing the external library's CSS as a string and injecting it directly into the Shadow DOM.

We leveraged Vite's ?inline feature to import the external library's CSS as a string and inject it directly into the Shadow DOM.

In Vite, you can disable automatic CSS injection using the ?inline query parameter. This feature allows you to receive the CSS content as a string.

import './foo.css' // Styles are added to the page
import otherStyles from './bar.css?inline' // Styles are NOT added

Using this feature, we wrote the following code:

export default function createShadowRoot(styles: string[]): ShadowRoot {
  const host = document.createElement('div')
  host.setAttribute('id', SHADOW_HOST_ID)
  const shadowRoot = host.attachShadow({ mode: 'open' })

  // 👇
  const globalStyleSheet = new CSSStyleSheet()
  globalStyleSheet.replaceSync(styles.join('\n'))
  shadowRoot.adoptedStyleSheets = [globalStyleSheet]

  document.body.appendChild(host)

  return shadowRoot
}

And when using this function, we imported the CSS files as follows:

'react-easy-crop/react-easy-crop.css?inline' // 👈

import { App } from './App'
import styles from '@/styles/index.css?inline'
import createShadowRoot from '@/utils/createShadowRoot'

function initApp() {
document.getElementById('back-top')?.remove()

const shadowRoot = createShadowRoot([styles, cropperStyles]) // 👈
createRoot(shadowRoot).render(<App />)
}

// ...

Through this approach, we were able to import external library styles as strings and inject them directly into the Shadow DOM. As a result, we confirmed that the react-easy-crop library's styles were properly applied inside the Shadow DOM.

The actual applied code can be found here.

5. Conclusion

As a result of applying Shadow DOM to the Gachon Tools project, we gained the following benefits:

1. Effectively resolved style conflict issues
2. Reduced development resources needed for styling
3. Provided consistent UI across all environments

Of course, there were unexpected issues during the development process, but resolving them helped deepen our understanding of Shadow DOM.