JavaScript Document browsingTopics() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Method
Decorative image with the word BROWSINGTOPICS

Definition

document.browsingTopics() returns a Promise that fulfills with up to three topic objects (one per recent epoch) for interest-based advertising. By default it also marks the current page as observed for topic calculation.

Pass the required arguments shown below. Check return values and browser support before you rely on the result.

Syntax

Call document.browsingTopics. Start with this line.

JavaScript
document.browsingTopics([options])
CallWhat it does
document.browsingTopics([options])Primary signature.
document.browsingTopics(...)Call with the arguments your case needs.

Built into the browser. Call browsingTopics(...) on document — no import required.

Library declarations
JavaScript
document.browsingTopics([options])

Parameters

ParameterDescription
options.skipObservationOptional. true = do not observe this visit (default false)

Return Value

Return ValueDescription
*Promise of topic object array (0–3)

JavaScript Examples

Example 1 — Await Topics Safely

Detect the method, await the Promise, and catch enrollment/policy errors.

JavaScript
async function getTopics() {
  if (typeof document.browsingTopics !== "function") {
    return "unsupported";
  }
  try {
    const topics = await document.browsingTopics();
    return topics.length + " topic(s)";
  } catch (err) {
    return err.name; // e.g. "NotAllowedError"
  }
}

console.log(await getTopics());
Try It Yourself

How It Works

  1. Detect first. Most browsers never shipped this method.
  2. Await the Promise. On success you get an array of topic objects.
  3. Catch denials. Missing enrollment or policy → NotAllowedError.
  4. Literacy goal. Recognize the API in old Privacy Sandbox demos — do not ship it.

Example 2 — skipObservation: true

Read topics without recording this page visit as observed (MDN option).

JavaScript
async function peekTopics() {
  if (typeof document.browsingTopics !== "function") {
    return "unsupported";
  }
  try {
    const topics = await document.browsingTopics({
      skipObservation: true
    });
    return JSON.stringify(topics);
  } catch (err) {
    return err.name;
  }
}

console.log(await peekTopics());
Try It Yourself

How It Works

  1. Default observes. A normal call can mark the hostname for topic calculation.
  2. Pass the flag. skipObservation: true skips that observation.
  3. Still async. You await the same Promise shape.
  4. Why it mattered. Sites that only wanted to read topics without contributing a visit used this option.

Example 3 — Topic Object Fields (Chrome Shape)

MDN example shape — useful when reading legacy logs or sample responses.

JavaScript
// Example object shape from MDN (Chrome-style)
const sample = {
  configVersion: "chrome.1",
  modelVersion: "1",
  taxonomyVersion: "1",
  topic: 43,
  version: "chrome.1:1:1"
};

console.log(sample.topic);   // 43
console.log(sample.version); // "chrome.1:1:1"
Try It Yourself

How It Works

  1. topic is the taxonomy ID number used to look up the interest label.
  2. Version fields describe which model/taxonomy produced the ID.
  3. version concatenates the three version strings with colons.
  4. Exact values vary by browser implementation — treat this as a sample shape.
Compatibility

Browser Support

Document.browsingTopics() is Deprecated and Non-standard on MDN. It was a Chromium Privacy Sandbox experiment. Do not rely on it in new code.

✓ Deprecated · Non-standard

Document.browsingTopics()

Historically Chromium-oriented. Firefox and Safari do not implement it. Removal is expected — feature-detect only for legacy literacy.

Legacy Deprecated API
Google Chrome Historical / withdrawing
Legacy
Microsoft Edge Chromium-era support
Legacy
Opera Chromium-era support
Legacy
Mozilla Firefox No (opposed)
No
Apple Safari No (opposed)
No
Internet Explorer No
No
browsingTopics() Do not use

Bottom line: Educational reference only. See the MDN browsingTopics() reference.

Frequently Asked Questions

It returns a Promise that fulfills with an array of up to three topic objects — one from each of the last three epochs — representing the user’s top topics for interest-based advertising (MDN).
MDN marks Document.browsingTopics() as Deprecated (pending removal) and Non-standard. Chrome withdrew certain Privacy Sandbox features including the Topics API. Do not use it in new production code.
A Promise resolving to an array of topic objects. Each object includes topic (ID), configVersion, modelVersion, taxonomyVersion, and version.
An optional boolean. When true, the browser does not record the current page visit as observed for topics calculation. Default is false.
It throws NotAllowedError if blocked by a browsing-topics Permissions Policy, or if the site is not enrolled in the Privacy Sandbox enrollment process.
MDN advises preferring Topics API HTTP header features when you can modify headers, and falling back to browsingTopics() only when headers cannot be changed — and only while the API still exists.

Next: caretPositionFromPoint()

Learn how to map a screen point to a text caret position.

caretPositionFromPoint() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

11 people found this page helpful

JavaScript Document ariaNotify() Method JavaScript Document caretPositionFromPoint() Method