Keyboard Shortcuts in Firefox Extensions: A Complete Guide

sTypingContext()) return;

switch (e.key) { case '/': e.preventDefault(); document.getElementById('search-input').focus(); break; case 'Escape': document.activeElement.blur(); break; case 'd': if (e.ctrlKey) break; // Don't intercept Ctrl+D (bookmark) toggleTheme(); break; } });

function isTypingContext() { const tag = document.activeElement.tagName; return tag === 'INPUT' || tag === 'TEXTAREA' || document.activeElement.isContentEditable; }

### 4. Focus Search on Any Key
Implement a new-tab pattern that routes alphanumeric keys to search without blocking native character input.

document.addEventListener('keydown', e => { if (isTypingContext()) return; if (e.ctrlKey || e.metaKey || e.altKey) return; if (e.key.length !== 1) return;

const searchInput = document.getElementById('search-input'); searchInput.focus(); // Don't preventDefault — let the character go into the search box });

### 5. Displaying Keyboard Shortcuts
Map shortcuts to a help overlay for discoverability.

const SHORTCUTS = [ { key: '/', description: 'Focus search' }, { key: 'Esc', description: 'Clear focus' }, { key: 'd', description: 'Toggle dark mode' }, { key: '?', description: 'Show this help' }, ];

document.addEventListener('keydown', e => { if (isTypingContext()) return; if (e.key === '?') { toggleHelpOverlay(); } });

### 6. Dynamic Shortcut Retrieval
Always query the actual user-assigned shortcut instead of hardcoding display strings.

async function getShortcutForCommand(commandName) { const commands = await browser.commands.getAll(); const cmd = commands.find(c => c.name === commandName); return cmd?.shortcut || 'unassigned'; }

// Display in settings UI const shortcut = await getShortcutForCommand('toggle-theme'); document.getElementById('shortcut-display').textContent = shortcut;

### 7. ARIA-Compliant Widget Navigation
Implement standard keyboard patterns for custom interactive components.

// Radio group keyboard navigation function handleRadioKeydown(e, items) { const currentIndex = items.indexOf(document.activeElement); let newIndex;

switch (e.key) { case 'ArrowDown': case 'ArrowRight': newIndex = (currentIndex + 1) % items.length; break; case 'ArrowUp': case 'ArrowLeft': newIndex = (currentIndex - 1 + items.length) % items.length; break; default: return; }

e.preventDefault(); items[newIndex].focus(); items[newIndex].click(); }

## Pitfall Guide
1. **Browser Shortcut Collision**: Never override native browser shortcuts (`Ctrl+T`, `Ctrl+W`, `Ctrl+N`, `Ctrl+L`, `F5`, `Ctrl+Shift+T`). Firefox silently blocks or prioritizes native bindings, causing silent command failures. Always validate against Mozilla's reserved key list.
2. **Cross-Platform Modifier Mismatch**: Windows and macOS interpret modifier keys differently. `Ctrl` on Windows maps to `Cmd` (MacCtrl) on macOS. Failing to use `MacCtrl` in `suggested_key` or checking `e.metaKey` in JS breaks shortcuts for ~35% of users.
3. **Context-Blind Key Interception**: Attaching `keydown` listeners without checking `document.activeElement` intercepts keystrokes meant for forms, content editors, or iframes. Always implement `isTypingContext()` guards before routing keys.
4. **Static Shortcut Display**: Hardcoding shortcut strings in settings UI or tooltips breaks when users reassign keys via `about:addons`. Always fetch live mappings using `browser.commands.getAll()` and cache them with `browser.commands.onChanged`.
5. **Focus Indicator Suppression**: Removing `outline` or `outline-offset` via `* { outline: none; }` destroys keyboard navigation visibility. Use `:focus-visible` to provide high-contrast, accessible focus rings only for keyboard users.
6. **Ignoring `Ctrl+Alt` Windows Restrictions**: Windows reserves `Ctrl+Alt+*` for AltGr and dead-key input methods. Extensions using these combinations will fail silently on Windows. Stick to `Ctrl+Shift+*` or `Alt+*` for reliable cross-OS behavior.
7. **Missing `preventDefault` on Navigation Keys**: Arrow keys, `Tab`, and `Escape` trigger browser-native navigation. Failing to call `e.preventDefault()` in custom widget handlers causes focus leakage and broken keyboard flows.

## Deliverables
**📘 Firefox Extension Keyboard Architecture Blueprint**
- Complete manifest schema for global & action shortcuts
- Background-to-content script message routing patterns
- Context-detection state machine (`isTypingContext` implementation)
- ARIA widget keyboard mapping matrix (radio, list, dialog, menubar)
- Dynamic shortcut retrieval & caching strategy with `browser.commands.onChanged`

**✅ Keyboard Support QA Checklist**
- [ ] Verify `manifest.json` `commands` block uses cross-platform modifiers (`Ctrl+Shift` or `MacCtrl`)
- [ ] Confirm no overlap with Firefox reserved shortcuts (`about:config` `ui.key.accelKey` validation)
- [ ] Test `isTypingContext()` against `<input>`, `<textarea>`, `[contenteditable="true"]`, and shadow DOM
- [ ] Validate `browser.commands.getAll()` returns user-assigned shortcuts in settings UI
- [ ] Audit focus management: `:focus-visible` applied, `outline: none` removed, Tab/Shift+Tab flow verified
- [ ] Cross-OS testing: Windows (`Ctrl`), macOS (`Cmd`/`MacCtrl`), Linux (`Ctrl`/`Alt`)
- [ ] Accessibility scan: Lighthouse/WAVE WCAG 2.1 AA keyboard navigation & focus order validation