Shadow DOM & Web Components – contenteditable.lab

Overview

When using contenteditable elements inside Shadow DOM or Web Components, several issues can arise due to DOM encapsulation and event isolation. Events may not bubble correctly, selection APIs may behave unexpectedly, and focus management can be inconsistent.

Key Concepts

Shadow DOM: Encapsulated DOM tree that isolates styles and structure
Event Bubbling: Events inside shadow DOM don't bubble to light DOM by default
Selection API: window.getSelection() may reference shadow DOM nodes that aren't accessible
Focus Management: Focus behavior may differ when contenteditable is inside shadow DOM
Composed Events: Use composed: true to allow events to cross shadow boundaries

Basic Usage

Creating a contenteditable element inside Shadow DOM is straightforward, but you'll encounter issues with events, selection, and focus.

// Basic Shadow DOM with contenteditable
class EditableComponent extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    shadow.innerHTML = `
      <style>
        .editor {
          padding: 1rem;
          border: 1px solid #ccc;
          min-height: 100px;
        }
      </style>
      <div class="editor" contenteditable="true">
        <!-- Content -->
      </div>
    `;
  }
}

customElements.define('editable-component', EditableComponent);

⚠️ Browser Support Issues

In Chrome on macOS, contenteditable may not work correctly inside Shadow DOM. Selection may be broken, focus may not work, and events may not fire correctly. Behavior is inconsistent across browsers.

Event Bubbling Issues

Events fired inside Shadow DOM don't bubble to the light DOM by default. This means event listeners on the host element won't receive events from contenteditable elements inside the shadow DOM.

// Event bubbling through shadow DOM boundaries
class EditableComponent extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    const editor = document.createElement('div');
    editor.contentEditable = 'true';
    shadow.appendChild(editor);
    
    // Listen inside shadow DOM
    editor.addEventListener('input', (e) => {
      console.log('Input event in shadow DOM');
      // Event won't bubble to light DOM by default
    });
    
    // Listen on host element (light DOM)
    this.addEventListener('input', (e) => {
      console.log('Input event on host');
      // May not fire for events inside shadow DOM
    });
  }
}

// Workaround: Dispatch custom events
class EditableComponentFixed extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    const editor = document.createElement('div');
    editor.contentEditable = 'true';
    shadow.appendChild(editor);
    
    // Forward events to host
    editor.addEventListener('input', (e) => {
      // Create new event that bubbles
      const customEvent = new CustomEvent('editor-input', {
        bubbles: true,
        composed: true, // Important: allows crossing shadow boundary
        detail: { originalEvent: e }
      });
      this.dispatchEvent(customEvent);
    });
  }
}

⚠️ Events Don't Bubble by Default

Standard DOM events (like input, beforeinput, focus) fired inside shadow DOM do not bubble to the light DOM. You must manually forward events using CustomEvent with composed: true.

Forwarding Events

To make events accessible from the light DOM, forward them as custom events with composed: true.

// Using composed: true for cross-boundary events
class EditableComponent extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    const editor = document.createElement('div');
    editor.contentEditable = 'true';
    shadow.appendChild(editor);
    
    // Forward all important events
    const eventsToForward = [
      'beforeinput', 'input', 'compositionstart',
      'compositionupdate', 'compositionend',
      'selectionchange', 'focus', 'blur'
    ];
    
    eventsToForward.forEach(eventType => {
      editor.addEventListener(eventType, (e) => {
        const customEvent = new CustomEvent(`editor-${eventType}`, {
          bubbles: true,
          composed: true, // Critical: allows crossing shadow boundary
          cancelable: e.cancelable,
          detail: {
            originalEvent: e,
            inputType: e.inputType,
            data: e.data,
            // ... other relevant properties
          }
        });
        this.dispatchEvent(customEvent);
      });
    });
  }
}

Selection API Issues

The Selection API may behave unexpectedly when contenteditable is inside Shadow DOM. window.getSelection() may reference nodes in shadow DOM that aren't directly accessible from the light DOM.

// Selection issues in Shadow DOM
class EditableComponent extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    const editor = document.createElement('div');
    editor.contentEditable = 'true';
    shadow.appendChild(editor);
    
    // getSelection() may not work correctly
    editor.addEventListener('selectionchange', () => {
      const selection = window.getSelection();
      // Selection may reference nodes in shadow DOM
      // which are not accessible from light DOM
      
      if (selection.rangeCount > 0) {
        const range = selection.getRangeAt(0);
        // range.startContainer may be in shadow DOM
        console.log(range.startContainer);
      }
    });
  }
}

// Workaround: Use shadow root's selection
class EditableComponentFixed extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    const editor = document.createElement('div');
    editor.contentEditable = 'true';
    shadow.appendChild(editor);
    
    editor.addEventListener('selectionchange', () => {
      // Access selection from shadow root context
      const shadowSelection = shadow.getSelection();
      if (shadowSelection.rangeCount > 0) {
        const range = shadowSelection.getRangeAt(0);
        // This works within shadow DOM context
        console.log(range.toString());
      }
    });
  }
}

⚠️ Selection May Reference Shadow DOM Nodes

When using window.getSelection(), the returned Range may reference nodes inside shadow DOM. These nodes are not directly accessible from the light DOM. Use shadowRoot.getSelection() when working within the shadow DOM context.

Selection Best Practices

Use shadowRoot.getSelection() when working inside shadow DOM
Save selection state as serializable data (node paths, offsets) rather than node references
Forward selection change events to light DOM using custom events
Test selection behavior across different browsers

Focus Management Issues

Focus behavior can be inconsistent when contenteditable is inside Shadow DOM. The focus() method may not work as expected in Chrome.

// Focus management in Shadow DOM
class EditableComponent extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    const editor = document.createElement('div');
    editor.contentEditable = 'true';
    shadow.appendChild(editor);
    
    // Focus may not work correctly
    this.addEventListener('click', () => {
      editor.focus(); // May not work in Chrome
    });
  }
}

// Workaround: Use activeElement
class EditableComponentFixed extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    const editor = document.createElement('div');
    editor.contentEditable = 'true';
    shadow.appendChild(editor);
    
    this.addEventListener('click', () => {
      // Check if already focused
      const activeElement = shadow.activeElement;
      if (activeElement !== editor) {
        editor.focus();
      }
    });
    
    // Also handle focus events
    editor.addEventListener('focus', () => {
      // Focus is working
    });
  }
}

⚠️ Focus May Not Work Correctly

In Chrome, calling focus() on a contenteditable element inside Shadow DOM may not work correctly. Use shadowRoot.activeElement to check focus state, and handle focus events carefully.

Slots & contenteditable

Using <slot> with contenteditable is not recommended. Contenteditable elements in slotted content may not work correctly.

// Using slots for contenteditable (not recommended)
class EditableComponent extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    shadow.innerHTML = `
      <style>
        .editor-wrapper {
          padding: 1rem;
          border: 1px solid #ccc;
        }
      </style>
      <div class="editor-wrapper">
        <slot></slot>
      </div>
    `;
  }
}

// Usage (problematic)
<editable-component>
  <div contenteditable="true">Content</div>
</editable-component>

// Problem: contenteditable in slotted content may not work correctly
// Better: Put contenteditable inside shadow DOM

⚠️ Avoid Slots for contenteditable

Placing contenteditable elements in slotted content (light DOM) while the component uses Shadow DOM can cause issues. The contenteditable may not work correctly, and events/selection may be inconsistent. Instead, create the contenteditable element inside the shadow DOM.

Workarounds & Best Practices

1. Forward Events with Custom Events

Always forward important events (beforeinput, input, composition, selectionchange) to the light DOM using custom events with composed: true.

2. Use Shadow Root Selection API

When working with selection inside shadow DOM, use shadowRoot.getSelection() instead of window.getSelection().

3. Serialize Selection State

When saving/restoring selection, serialize it as node paths and offsets rather than storing node references, which may not be accessible across shadow boundaries.

4. Handle Focus Carefully

Check shadowRoot.activeElement to verify focus state, and forward focus/blur events to light DOM.

5. Avoid Slots for contenteditable

Don't use slots for contenteditable content. Create contenteditable elements directly inside the shadow DOM.

6. Test Across Browsers

Shadow DOM behavior varies significantly across browsers. Test thoroughly on Chrome, Firefox, Safari, and Edge.

Platform-Specific Issues & Edge Cases

Browser-Specific Behavior

Chrome/Edge

Focus Issues: focus() may not work correctly on contenteditable inside shadow DOM
Selection Issues: Selection may be broken or inconsistent
Event Bubbling: Events don't bubble to light DOM by default - must use composed: true

Firefox

Better Support: Generally better support for contenteditable in shadow DOM
Event Handling: Events may still need forwarding for consistency

Safari

Limited Support: Shadow DOM support may be limited in older Safari versions
Selection: Selection behavior may differ from Chrome

OS & Device-Specific Behavior

Desktop

Mouse Interaction: Click events and focus may behave differently
Keyboard Navigation: Arrow keys and selection may be affected

Mobile

Touch Interaction: Touch events may not bubble correctly
Virtual Keyboard: Keyboard behavior may be inconsistent
Selection Toolbar: Mobile selection toolbars may not work correctly

General Edge Cases

Nested Shadow DOM: Multiple levels of shadow DOM can compound issues
Dynamic Content: Adding/removing contenteditable elements dynamically may cause issues
IME Composition: IME composition may not work correctly inside shadow DOM
Clipboard Operations: Copy/paste may be affected by shadow DOM boundaries

Alternative Approaches

1. Use Light DOM Instead

If possible, avoid using Shadow DOM for contenteditable elements. Use light DOM with scoped styles using CSS modules or scoped stylesheets.

2. Use Declarative Shadow DOM

Declarative Shadow DOM (supported in newer browsers) may have better compatibility, but issues may still persist.

3. Hybrid Approach

Keep contenteditable in light DOM but wrap it in a Web Component that handles styling and behavior through the component's API rather than shadow DOM.