chrome.tabs.query(): Find the Right Tabs Without Guessing

Choose the scope deliberately

chrome.tabs.query({}) returns tabs across eligible windows. chrome.tabs.query({ currentWindow: true }) narrows the result to the extension context's current window. chrome.tabs.query({ active: true, lastFocusedWindow: true }) follows Chrome's documented pattern for finding the user's likely current tab from a service worker.

Current window and last focused window are not interchangeable. An extension page can have its own window context, while a service worker may fall back to the last active browser window. State which behavior your button promises before choosing a query filter.

• Chrome tabs.query reference and current-tab example

Treat the result as a snapshot

The Promise resolves to an array of Tab objects, not a live collection. A tab can navigate, move, close or become inactive before the user clicks a result. When an action matters, re-fetch the selected tab by id and compare its current URL or window with the snapshot before acting.

For an inventory, save only the fields the task needs: id, windowId, groupId, active status and permitted metadata. Browser tab IDs identify objects during a browser session; they are not durable IDs for a saved workspace. Use a separate record ID for persisted notes.

Handle metadata permissions and optional fields

Filtering by URL or displaying titles requires the right tabs or host access. Without it, your extension may receive Tab objects but not the sensitive fields it expected. Check permissions before building a search UI, and show a useful empty or limited state instead of substituting fabricated titles.

A robust mapper skips tabs without an id and uses title only when present. It should also decide whether chrome:// and other non-web addresses belong in the list. An HTTPS-only saved-source feature needs a stricter filter than an inventory of every browser tab.

• Tabs API permission guide

Build a useful tab finder

Start with chrome.tabs.query({ currentWindow: true }) when the interface clearly refers to one window. Normalize only text you are allowed to read, then match user terms against title and hostname. Display the exact window and group context so two pages with identical titles are distinguishable.

Do not silently close duplicates based on title. Same-looking tabs can contain different account sessions or unsaved forms. A finder should help the person choose; any cleanup action needs a separate confirmation and a fresh tab check.

• Find and close duplicate tabs safely

Idea: an explainable project tab picker

Create a picker that lists candidate tabs with title, domain, window and group, then lets the person select exactly which links belong to a project note. Keep the original browser tabs open until the saved list is verified.

The picker can also show why a tab was omitted: missing permission, unsupported internal URL or no stable web address yet. That explanation is more useful than a mysterious count that does not match the tab strip.

Test the edges

Test multiple windows, a rapidly navigating tab, a tab closed between query and click, a page with no title and a browser-internal tab. Include an incognito test only when your extension has been allowed there.

If the action calls a second API, handle its rejected Promise. A successful query does not guarantee the target tab still exists by the time the next call runs.