Documentation
Everything you need to install, use, and understand Quick Perplexes — a lightweight browser extension that brings a Spotlight-style overlay to every webpage, routing your searches directly to Perplexity.ai.
Overview
Quick Perplexes adds a persistent keyboard shortcut (Ctrl+`) to every webpage you visit. Pressing it opens a floating search overlay — built inside a closed Shadow DOM so it never conflicts with the host page's styles or scripts. Type a query, press Enter, and Perplexity.ai opens in a new tab with your search already running.
The extension has no backend, collects no data, and requires only the
tabs
permission (to open the new tab). It is free and open-source under the MIT
license.
Installation
Firefox
Chrome (manual load)
The Chrome Web Store listing is pending review. In the meantime you can load the extension manually from source.
manifest.json).
Usage guide
Opening the overlay
Press Ctrl+` (backtick, the key above Tab) on any webpage. The overlay appears centred on screen, the input is focused, and the host page's own keyboard shortcuts are suspended until you close it.
On macOS the same shortcut works — the extension uses
e.code
rather than e.key
to handle keyboard layout differences reliably.
Submitting a search
Type your query and press Enter. Quick Perplexes constructs a Perplexity.ai search URL and opens it in a new tab. The overlay closes automatically and the input is cleared for the next use.
You can also use modifier keys to control how results open: Ctrl+Enter opens in a background tab, Shift+Enter opens in a new window, and Alt+Enter opens in a floating popup window anchored to the bottom-right corner of the screen.
Pre-filling with selected text
Select any text on the page before pressing Ctrl+`. The overlay opens with that text already in the input, ready to submit or edit. The selection is highlighted so you can immediately start typing to replace it.
Closing the overlay
You can close the overlay without searching in three ways:
- Press Esc
- Click anywhere outside the overlay (backdrop click)
- Press Ctrl+` again to toggle it closed
Toolbar icon
Clicking the Quick Perplexes icon in the browser toolbar opens perplexity.ai directly in a new tab — a quick shortcut when you want the full interface rather than the overlay.
Keyboard shortcuts
| Shortcut | Action | Context |
|---|---|---|
| Ctrl+` | Open / close overlay | Any webpage |
| Enter | Search in new tab | Overlay open |
| Ctrl+Enter | Search in background tab | Overlay open |
| Shift+Enter | Search in new window | Overlay open |
| Alt+Enter | Search in floating popup | Overlay open |
| Esc | Close overlay without searching | Overlay open |
| Tab / Shift+Tab | Focus stays inside overlay | Overlay open |
| Backdrop click | Close overlay without searching | Overlay open |
Architecture
Quick Perplexes is a Manifest V3 extension with exactly two scripts. There are no build steps, no npm packages, and no bundler — the source is what ships.
background.js
Service worker. Single responsibility: listens for toolbar icon clicks and opens perplexity.ai in a new tab via chrome.tabs.create.
content.js
Injected into every page at document_start. Manages the full overlay lifecycle: creation, toggle, query submission, focus trapping, and cleanup.
overlay.css
Stylesheet loaded at runtime via fetch(chrome.runtime.getURL()) and injected as a <style> tag inside the Shadow DOM.
manifest.json
MV3 manifest. Declares the tabs permission, the content script, the service worker, and overlay.css as a web-accessible resource.
Shadow DOM isolation
The overlay is attached to a host element as a closed Shadow DOM.
This means the overlay's CSS is completely isolated from the host page — no
style leaks in either direction, regardless of what CSS frameworks or resets
the page uses. The host element itself is a plain <div>
appended to document.body.
Overlay lifecycle
Keyboard event capture
The Ctrl+` listener is registered in the capture phase
(useCapture: true),
so it fires before any host-page handlers. While the overlay is open,
stopPropagation()
is called on all keydown
events to prevent host-page shortcuts from firing.
URL construction
The buildSearchUrl(query)
function (the only logic with unit tests) encodes the query and appends it to the
Perplexity search endpoint. Tests live in tests/test.html
and run automatically when opened in a browser.
Cross-browser compatibility
Firefox support was added in v0.5.0. The manifest includes a
browser_specific_settings.gecko
block with the extension ID and minimum Firefox version (140+). The
build.js script packages
the same source into separate Chrome and Firefox zips using a pure-Node ZIP writer
with no external dependencies.
Version history
data_collection_permissions. build.js added — pure-Node script that packages separate Chrome and Firefox zips with deterministic timestamps. Extension icons updated with rounded corners.
e.key to e.code to handle macOS keyboard layout differences. Keydown propagation from the Shadow DOM stopped to prevent host-page shortcut interference.
isCreating flag. Input cleared on close. Esc propagation stopped. Switched to window.open() (content scripts cannot call chrome.tabs.create). Unit tests added for URL builder.
Contributing
Quick Perplexes is open-source under the MIT license. Contributions, bug reports, and feature ideas are welcome via GitHub.
- Bug reports & feature requests: open an issue
- Running tests: open
tests/test.htmlin any browser — results appear immediately. - Building packages: run
node build.jsto generatedist/quick-perplexes-chrome-*.zipand the Firefox equivalent. - Reloading after changes: in Chrome, visit
chrome://extensionsand click the refresh icon on the extension card.