How to Fix: Web components styling not work with CSS Modules

8 min read Aldawsari
8 min read

The inherent encapsulation of Web Components’ Shadow DOM directly clashes with the local scoping mechanisms of CSS Modules, leading to frustrating scenarios where your carefully crafted styles simply don’t apply. This tutorial unravels this common Next.js styling puzzle, providing robust solutions to bridge the gap and restore your development sanity.

Understanding the Root Cause: Encapsulation vs. Scoping

The core of this issue lies in the fundamental design principles of both CSS Modules and Web Components with Shadow DOM:

  • CSS Modules: Local Scoping for the Light DOM

    When you import a .module.css file in a Next.js React component, the build process transforms your class names (e.g., .button becomes .button_module__btn__abc12). These unique, locally scoped class names are then applied to elements within the Light DOM — the regular DOM tree that your React component renders. This system prevents style collisions across different React components.

  • Web Components & Shadow DOM: Encapsulated Styling

    Web Components, particularly those utilizing a Shadow DOM (created via this.attachShadow({ mode: 'open' })), are designed for strong encapsulation. The Shadow DOM creates an isolated sub-tree of the DOM that prevents external styles from leaking in and internal styles from leaking out. This isolation is a powerful feature for building reusable, framework-agnostic components, but it also means that CSS Module styles defined in the parent Light DOM naturally cannot penetrate this boundary.

  • The Conflict

    When you try to apply a CSS Module class to your custom element (e.g., <my-button className={styles.myButtonStyle}>), the CSS Module styles are applied correctly to the host element itself (the <my-button> tag) in the Light DOM. However, these styles do not magically traverse into the internal structure of my-button that resides within its Shadow DOM. The elements inside the Shadow DOM remain unstyled by the external CSS Module.

Solution 1: Theming with CSS Variables (Recommended)

This is often the most elegant and recommended approach for allowing external customization while respecting the Shadow DOM’s encapsulation. You use CSS Modules to define CSS Custom Properties (Variables) on the host element in the Light DOM, and then consume these variables directly within the Web Component’s Shadow DOM.

Solution 2: Directly Injecting Styles via `adoptedStyleSheets`

For more comprehensive styling, especially when you have an entire stylesheet you want to apply to a Shadow DOM, adoptedStyleSheets is the modern, performant solution. It allows you to share CSSStyleSheet objects across multiple Shadow DOMs efficiently. This approach typically involves creating a separate, plain .css file for your Web Component’s internal styles and then loading and adopting it.

Solution 3: Dynamic <style> Tag Injection (Fallback)

As a more backward-compatible or simpler alternative, you can programmatically create a <style> element within the Shadow DOM and populate it with CSS content. While functional, it’s generally less performant than adoptedStyleSheets for shared styles and can lead to more memory usage if many instances of the component have unique styles.

Step-by-Step Implementation

Let’s walk through integrating a Web Component with a Next.js application, applying the solutions discussed.

1. Define Your Web Component (components/my-button.js)

First, create your custom element. Notice how it uses CSS variables (var(--...)) for external customization and prepares for adoptedStyleSheets.


// components/my-button.js

class MyButton extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' }); // Create Shadow DOM
    this.loadExternalStyles(); // Load external stylesheet (for Solution 2)
    this.render();
  }

  // Method to render the component's internal structure
  render() {
    this.shadowRoot.innerHTML = `
      <style>
        /* Base internal styles for the button, consuming CSS variables */
        button {
          padding: var(--button-padding, 10px 20px);
          border: var(--button-border, 1px solid blue);
          border-radius: var(--button-border-radius, 5px);
          background-color: var(--button-bg, #007bff);
          color: var(--button-color, white);
          cursor: pointer;
          font-size: var(--button-font-size, 16px);
          font-family: sans-serif;
        }
        button:hover {
          background-color: var(--button-bg-hover, #0056b3);
        }
      </style>
      <button><slot>Click Me</slot></button>
    `;
  }

  // Method to load and adopt an external stylesheet using adoptedStyleSheets (Solution 2)
  async loadExternalStyles() {
    if (!this.shadowRoot.adoptedStyleSheets) return; // Not supported in all browsers

    try {
      // For a Next.js app, place 'my-button-shared.css' in the 'public' directory
      // or use a build-time import (e.g., using a raw-loader if you configure webpack).
      // Fetching from 'public' is simplest for demonstration.
      const response = await fetch('/my-button-shared.css');
      const cssText = await response.text();
      const sheet = new CSSStyleSheet();
      sheet.replaceSync(cssText);
      this.shadowRoot.adoptedStyleSheets = [...this.shadowRoot.adoptedStyleSheets, sheet];
    } catch (error) {
      console.error('Failed to load shared styles for MyButton:', error);
    }
  }
}

// Define the custom element, guarding against redefinition in dev mode
if (typeof window !== 'undefined' && !customElements.get('my-button')) {
  customElements.define('my-button', MyButton);
}

2. Create a Shared Stylesheet (public/my-button-shared.css)

This is a plain CSS file, not a CSS Module. It will be fetched and adopted by the Web Component for additional shared styling (Solution 2).


/* public/my-button-shared.css - Shared styles for MyButton */
button {
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
  transition: all 0.2s ease-in-out;
  font-weight: 600;
}
button:active {
  transform: translateY(1px);
}

3. Create a CSS Module for Next.js Component (pages/styles.module.css)

Here, we define CSS Module classes for our Next.js page. Crucially, we use them to set CSS Variables on the host <my-button> element (Solution 1).


/* pages/styles.module.css */

.container {
  padding: 20px;
  text-align: center;
}

.heading {
  color: #333;
  margin-bottom: 30px;
}

/* Apply CSS Module classes to the custom element host */
.primaryButton {
  margin: 10px;
  /* CSS Variables for the Web Component's internal use */
  --button-bg: #28a745; /* Green background */
  --button-bg-hover: #218838;
  --button-color: white;
  --button-padding: 12px 24px;
  --button-border-radius: 8px;
  /* You can also style the host element directly with CSS Modules */
  border: 2px solid var(--button-bg);
}

.secondaryButton {
  margin: 10px;
  --button-bg: #6c757d; /* Grey background */
  --button-bg-hover: #5a6268;
  --button-color: white;
  --button-padding: 8px 16px;
  --button-border-radius: 4px;
  border: 2px solid var(--button-bg);
}

4. Integrate in Your Next.js Page (pages/index.js)

Import your CSS Module and render your custom elements. Use useEffect to dynamically import the Web Component to prevent SSR (Server-Side Rendering) issues, as custom elements rely on the browser’s DOM APIs.


// pages/index.js
import { useEffect } from 'react';
import styles from './styles.module.css'; // Your CSS Module for the page

export default function HomePage() {
  useEffect(() => {
    // Dynamically import the Web Component on the client-side only
    // This prevents issues where `customElements` is not defined during SSR
    import('../components/my-button');
  }, []);

  return (
    <div className={styles.container}>
      <h1 className={styles.heading}>Web Components & CSS Modules in Next.js</h1>
      
      <!-- Using Solution 1: CSS Variables defined by CSS Modules -->
      <my-button className={styles.primaryButton}>
        <span>Primary Action</span>
      </my-button>

      <my-button className={styles.secondaryButton}>
        <span>Secondary Action</span>
      </my-button>

      <my-button>
        <span>Default Button</span>
      </my-button>
    </div>
  );
}

Common Edge Cases and Considerations

  • Server-Side Rendering (SSR) Challenges: Web Components often rely heavily on browser APIs (like customElements). Dynamically importing your Web Component within a useEffect hook, as shown above, is crucial for Next.js to avoid SSR errors.
  • FOUC (Flash of Unstyled Content): If your external stylesheets for adoptedStyleSheets are loaded asynchronously (e.g., via fetch), there might be a brief moment before styles are applied. Consider a loading state or critical CSS inlined if this is an issue.
  • CSS Variable Fallbacks: Always provide fallback values (e.g., var(--my-var, default-value)) within your Web Component’s internal styles. This ensures the component has a sensible default appearance even if external variables aren’t defined.
  • Tooling and Build Process for `adoptedStyleSheets`: Fetching a .css file from the public directory is straightforward but means the CSS isn’t bundled. For more integrated solutions, you might explore custom Webpack configurations in Next.js (via next.config.js) to use loaders (like raw-loader) that import raw CSS strings directly into your JavaScript, allowing you to create CSSStyleSheet objects at build time.
  • Styling the Host Element: Remember that CSS Modules *can* directly style the custom element’s host tag (e.g., <my-button>). This is useful for layout, spacing, or borders around the component itself, distinct from its internal styling.

FAQ

Q: Can I use CSS Modules *inside* my Web Component’s Shadow DOM?

A: Not directly in the typical sense. CSS Modules are a build-time transformation for the Light DOM. To get locally scoped styles into your Shadow DOM, you would need a build step that extracts the processed CSS from a CSS Module and then programmatically injects that raw CSS string into a <style> tag or as an adoptedStyleSheet within your Shadow DOM. This adds significant complexity and usually negates the simplicity benefits of Shadow DOM’s direct styling.

Q: What about global CSS files? Do they penetrate the Shadow DOM?

A: By default, global CSS files that are included outside the Shadow DOM will not penetrate it. The Shadow DOM provides a strong encapsulation barrier. However, some very specific, rarely used global CSS rules (like those affecting inherited properties, or if the Shadow DOM mode is ‘closed’ and you’re not careful with how it’s attached) might have indirect effects. For direct internal styling, explicit injection (like adoptedStyleSheets or CSS Variables) is required.

Q: Why choose adoptedStyleSheets over just creating a <style> tag for each Web Component instance?

A: adoptedStyleSheets offers several advantages:

  • Performance: The stylesheet object is created once and reused across all instances of the Web Component, saving memory and parsing time.
  • Maintainability: It’s cleaner to manage external stylesheets separately.
  • Dev Tools: Browser developer tools often provide better inspection and debugging capabilities for adoptedStyleSheets.
  • Dynamic Updates: You can update a CSSStyleSheet object, and those changes will propagate to all Shadow DOMs that have adopted it.

A dynamic <style> tag, while simpler to implement initially, duplicates the CSS content for every component instance, which can be inefficient.

Leave a Reply

Your email address will not be published. Required fields are marked *