I Built a Gmail Template Extension — Here's What I Learned Fighting Gmail's DOM

If you've ever built a Chrome extension that touches Gmail's UI, you know the pain. Obfuscated class names, aggressive keyboard event capturing, mutation storms that freeze your tab — Gmail is a hostile environment for extension developers.

I spent weeks building SnapReply for Gmail, a template insertion extension that lets you fire off common email replies in seconds. Along the way, I accumulated a collection of hard-won lessons about wrangling Gmail's DOM. This article shares the technical challenges and the patterns I used to solve them.

The Problem: Email Replies Are Repetitive

Most knowledge workers send dozens of emails a day, and a surprising number of those are near-identical responses. Gmail does have a built-in Templates feature (formerly Canned Responses), but it's buried under menus and lacks variable support, shortcuts, or any real customization.

I wanted something that would let me type /thanks in a compose window and have it instantly expand into a full response — complete with dynamic dates, recipient names, and conditional blocks. That meant building a content script that deeply integrates with Gmail's compose UI.

Here's where the fun begins.

Challenge 1: Selector Fallback Chains

Gmail's UI isn't built with React, Vue, or any public framework. It uses Google's proprietary closure-based rendering system. Class names like .AD, .nH, and .Am.aiL are generated by an internal build tool and can change with any deployment.

Relying on a single CSS selector is a recipe for your extension breaking every few weeks. Instead, I built a tiered selector system that tries semantically stable selectors first and falls back to fragile class-based ones:

type SelectorTier = {
  primary: string;
  fallbacks: string[];
};

const SELECTORS = {
  composeBody: {
    primary: '[role="textbox"][aria-label][g_editable="true"]',
    fallbacks: [
      'div[aria-label][contenteditable="true"][g_editable="true"]',
      '.Am.aiL',
      'div[contenteditable="true"].editable',
    ],
  } as SelectorTier,
  composeToolbar: {
    primary: 'tr.btC td.gU',
    fallbacks: ['.btC .gU', 'td.gU.aXw'],
  } as SelectorTier,
  // ... more selectors
};

function querySelector(
  selector: GmailSelector,
  root: Element | Document = document
): Element | null {
  const tier = SELECTORS[selector];
  const el = root.querySelector(tier.primary);
  if (el) return el;

  for (const fallback of tier.fallbacks) {
    const found = root.querySelector(fallback);
    if (found) return found;
  }
  return null;
}

The key insight: WAI-ARIA attributes (role, aria-label) and Gmail-specific attributes (g_editable) are far more stable than class names. Google rarely changes accessibility attributes because doing so would break their own internal testing and screen reader support. The obfuscated class names are only there as a last resort.

This pattern has kept the extension working through multiple Gmail updates without code changes.

Challenge 2: MutationObserver — The attributes Trap

To detect when a user opens a new compose window, I use a MutationObserver on document.body. This seems straightforward, but there is one critical configuration mistake that will freeze the entire Gmail tab:

this.observer = new MutationObserver(() => {
  if (this.debounceTimer) clearTimeout(this.debounceTimer);
  this.debounceTimer = setTimeout(() => this.scanForComposes(), 50);
});

this.observer.observe(document.body, {
  childList: true,
  subtree: true,
  // NEVER add attributes: true — causes infinite loops on Gmail
});

Never set attributes: true when observing Gmail's DOM tree. Gmail constantly mutates element attributes — style changes, ARIA state updates, internal state flags — at an extraordinary rate. Enabling attribute observation triggers an avalanche of mutation callbacks that creates a positive feedback loop, effectively hanging the browser tab.

The comment you see in the code isn't just documentation; it's a scar from a debugging session that cost me an entire afternoon.

Two additional patterns help here:

1. Debouncing the callback at 50ms to batch rapid DOM changes into a single scan
2. WeakMap-based tracking to avoid processing the same compose window twice:

private trackedComposes = new WeakMap<Element, boolean>();

private scanForComposes(): void {
  const composes = querySelectorAll('composeContainer');
  for (const el of composes) {
    if (!this.trackedComposes.has(el)) {
      this.trackedComposes.set(el, true);
      this.onNewCompose(el);
    }
  }
}

Using WeakMap instead of a Set means compose elements are automatically garbage-collected when Gmail removes them from the DOM, preventing memory leaks in long-lived sessions.

Challenge 3: Gmail Hijacks Your Keyboard Events

Gmail has aggressive global keyboard shortcuts. Press c anywhere on the page and it opens a new compose window. Press e and it archives the current conversation. This is great for power users, but terrible for extension developers who need text input fields.

When I added a search bar to filter templates, typing c would open a compose window instead of inserting the letter. Gmail captures keyboard events at the document level before they reach your input elements.

The fix is to stop event propagation on every keyboard-related event:

const stopGmailCapture = (
  e: React.KeyboardEvent | React.CompositionEvent
) => {
  e.stopPropagation();
};

// Applied to every input element:
<input
  onKeyDown={stopGmailCapture}
  onKeyUp={stopGmailCapture}
  onKeyPress={stopGmailCapture}
  onCompositionStart={stopGmailCapture}
  onCompositionUpdate={stopGmailCapture}
  onCompositionEnd={stopGmailCapture}
  // ...
/>

Notice the three composition* event handlers. These are critical for CJK (Chinese/Japanese/Korean) input methods (IMEs). Without them, typing in Japanese or Chinese triggers Gmail shortcuts during the composition phase, producing garbled input or unexpected Gmail actions. If your extension has any international user base, you cannot skip these.

Challenge 4: Shadow DOM for Style Isolation

Gmail's CSS is enormous and opinionated. If you inject a regular DOM element, Gmail's styles will immediately override your carefully crafted UI. Conversely, your styles might break Gmail's layout.

The solution is Shadow DOM with an aggressive reset:

const host = document.createElement('div');
host.id = 'snapreply-root';
document.body.appendChild(host);

const shadowRoot = host.attachShadow({ mode: 'closed' });

const sheet = new CSSStyleSheet();
sheet.replaceSync(`:host { all: initial; }\n${contentCss}`);
shadowRoot.adoptedStyleSheets = [sheet];

Three things to note:

1. :host { all: initial; } resets every inherited CSS property. Without this, Gmail's font sizes, colors, and line heights leak into your shadow tree.
2. mode: 'closed' prevents Gmail's scripts from reaching into your shadow root via element.shadowRoot.
3. adoptedStyleSheets injects your CSS (I use Tailwind) without <style> tags, which is more performant for constructable stylesheets.

This approach means your extension's UI is a completely self-contained island inside Gmail's page. No style conflicts, no z-index wars, no specificity battles.

Challenge 5: Template Insertion and the execCommand Dilemma

Gmail's compose editor is a contenteditable div — essentially a rich text editor built on browser primitives. When you insert HTML into it, you need to consider undo/redo support. If you naively set innerHTML, the user loses their entire undo history.

The strategy is a two-tier fallback:

function insertAtCursor(body: HTMLElement, html: string): boolean {
  // Tier 1: execCommand for undo support
  try {
    const success = document.execCommand('insertHTML', false, html);
    if (success) return true;
  } catch {
    // Fall through to Range API
  }

  // Tier 2: Range API (no undo support, but reliable)
  const selection = window.getSelection();
  if (selection && selection.rangeCount > 0) {
    const range = selection.getRangeAt(0);
    range.deleteContents();
    const frag = range.createContextualFragment(html);
    range.insertNode(frag);
    range.collapse(false);
    return true;
  }

  return false;
}

Yes, document.execCommand is officially deprecated. But for contenteditable environments, it remains the only way to insert HTML while preserving the browser's native undo stack. The Clipboard API and Input Events Level 2 spec offer insertReplacementText and insertFromPaste, but browser support is inconsistent and Gmail's editor doesn't respond to them reliably.

There is also a subtlety with setting the subject line. Gmail uses React-like controlled inputs where setting .value directly doesn't trigger internal state updates. You need to use the native property setter:

const nativeSetter = Object.getOwnPropertyDescriptor(
  HTMLInputElement.prototype, 'value'
)?.set;

if (nativeSetter) {
  nativeSetter.call(subjectInput, subject);
} else {
  subjectInput.value = subject;
}

subjectInput.dispatchEvent(new Event('input', { bubbles: true }));
subjectInput.dispatchEvent(new Event('change', { bubbles: true }));

This bypasses any framework-level getter/setter overrides and ensures Gmail's internal model sees the change.

Challenge 6: Shortcut Expansion in contenteditable

One of SnapReply's features is slash-command shortcuts: type /thanks and press Space, and it expands into a full template. Implementing this inside a contenteditable div is trickier than it sounds.

You can't just listen for input events and regex the entire textContent — that would be O(n) on every keystroke and would fail with rich text nodes. Instead, the watcher reads only the text node at the current cursor position:

private getTextBeforeCursor(): string | null {
  const sel = window.getSelection();
  if (!sel || sel.rangeCount === 0) return null;

  const range = sel.getRangeAt(0);
  if (!range.collapsed) return null;

  const textNode = range.startContainer;
  if (textNode.nodeType !== Node.TEXT_NODE) return null;

  return (textNode.textContent || '').slice(0, range.startOffset);
}

When a match is found and the user hits Space, the watcher needs to surgically remove just the shortcut text and replace it with the template. This uses Range API manipulation on the specific text node — deleting only the /keyword characters and repositioning the cursor at the deletion point before the template engine takes over.

Bonus: Dark Mode Detection Without Gmail APIs

Gmail doesn't expose a public API for its current theme. To support dark mode, I calculate the perceived luminance of document.body's background color:

function isGmailDarkMode(): boolean {
  const bg = getComputedStyle(document.body).backgroundColor;
  const match = bg.match(/\d+/g);
  if (!match || match.length < 3) return false;
  const [r, g, b] = match.map(Number);
  const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
  return luminance < 0.5;
}

This uses the standard luminance formula (ITU-R BT.601) and works regardless of which specific dark theme the user has selected. Simple, but effective.

Lessons Learned

After building SnapReply, here are the principles I'd share with anyone building a Gmail extension:

1. Never trust class names. Use ARIA roles, name attributes, and Gmail-specific attributes as your primary selectors. Keep class-based selectors only as fallbacks.

2. Fear the MutationObserver. Gmail's DOM is volcanic. Observe only childList changes, debounce aggressively, and use WeakMap to deduplicate.

3. Stop all event propagation. Gmail's keyboard handling is greedy. If you render any interactive UI, call stopPropagation() on every keyboard and composition event.

4. Use Shadow DOM with :host { all: initial }. This is non-negotiable for any extension injecting UI into Gmail.

5. execCommand is deprecated but not dead. For contenteditable undo support, it's still the most reliable option in 2026.

6. Test with IME input. If you only test with a Latin keyboard, you'll miss composition event bugs that affect a large portion of your potential user base.

Try It Out

If you spend any amount of time replying to emails, give SnapReply a try. The free tier includes 10 templates with slash-command shortcuts, variable support, and folder organization — enough to cover most people's daily reply patterns.

Chrome Web Store

chromewebstore.google.com

If you've built a Gmail extension yourself, I'd love to hear what traps you fell into. Drop a comment below — misery loves company when it comes to Gmail's DOM.

---

Other tools I've built:

SnippetVault - Code Snippet Manager & Saver for Developers - Chrome Web Store

Save code snippets from any webpage with one click. Syntax highlighting, tags, search & one-click copy. Free tool for developers.

chromewebstore.google.com

PageMemo - Notes for Web Pages & URL-Linked Memos - Chrome Web Store

Take notes linked to specific web pages. Auto-save, no account required. Your notes appear when you revisit the page.

chromewebstore.google.com