e Solution
The architecture combines declarative manifest configuration, background command routing, context-aware in-page listeners, and ARIA-compliant focus management.
1. Declarative Global Commands (manifest.json)
Define shortcuts at the extension level to leverage Firefox's native key routing and user reassignment capabilities.
{
"commands": {
"_execute_action": {
"suggested_key": {
"default": "Ctrl+Shift+W"
},
"description": "Open Weather & Clock Dashboard"
},
"toggle-theme": {
"suggested_key": {
"default": "Ctrl+Shift+D"
},
"description": "Toggle dark/light mode"
}
}
}
Available modifiers: Ctrl, Alt, Shift, MacCtrl (Mac Cmd key)
Note: Ctrl+Alt+* combinations are blocked on Windows. Use Ctrl+Shift+* for cross-platform shortcuts.
2. Background Command Listeners
Route global shortcuts through the background script to decouple UI from core logic.
browser.commands.onCommand.addListener((command) => {
switch (command) {
case 'toggle-theme':
toggleTheme();
break;
// other commands...
}
});
3. Context-Aware In-Page Navigation
Prevent key interception during user input by validating the active element context.
document.addEventListener('keydown', e => {
// Don't intercept when user is typing
if (isTypingContext()) 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;
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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
