JavaScript Navigator permissions Property

What You’ll Learn

navigator.permissions is a read-only property that returns a Permissions object — the entry point to the Permissions API. Learn query(), the granted / prompt / denied states, MDN’s geolocation example, change listeners, five examples, and try-it labs.

Introduction

Powerful browser features — location, camera, notifications, and more — need user permission. Calling those APIs blindly can surprise users with prompts or fail silently after a denial.

navigator.permissions gives you a Permissions object so you can ask what the status is before (or after) you request a feature. MDN’s classic example checks geolocation and only shows a map when access is granted.

Understanding the permissions Property

Reading navigator.permissions does not return a Boolean. It returns a Permissions object. From there you call query({ name: "..." }) and get a PermissionStatus whose state is one of:

• granted — permission is allowed; you can use the feature.
• prompt — the browser may ask the user when you request it.
• denied — blocked; offer an alternative path, do not nag.
• Read-only entry point — you do not assign to navigator.permissions.
• Baseline — Widely available (MDN, since September 2022).

📝 Syntax

General form of the property:

navigator.permissions

Value

• A Permissions object used to query permission status.

Common patterns

// Feature-detect, then query (MDN-style):
if (navigator.permissions) {
  navigator.permissions.query({ name: "geolocation" }).then((result) => {
    if (result.state === "granted") {
      // showMap();
    } else if (result.state === "prompt") {
      // showButtonToEnableMap();
    }
    // Do nothing special if denied.
  });
}

Examples Gallery

Examples follow MDN navigator.permissions patterns. Prefer Try It Yourself. Some permission name values differ by browser — always catch errors.

const supported = "permissions" in navigator;
console.log(supported ? "permissions available" : "permissions missing");

permissions available

async function checkGeoPermission() {
  if (!navigator.permissions) {
    console.log("Permissions API missing");
    return;
  }
  const result = await navigator.permissions.query({ name: "geolocation" });
  if (result.state === "granted") {
    console.log("granted — showMap()");
  } else if (result.state === "prompt") {
    console.log("prompt — showButtonToEnableMap()");
  } else {
    console.log("denied — do not nag");
  }
}

checkGeoPermission();

prompt — showButtonToEnableMap()
(or granted / denied depending on your site settings)

async function geoStatusMessage() {
  if (!navigator.permissions) return "Permissions API not available";
  const { state } = await navigator.permissions.query({ name: "geolocation" });
  const messages = {
    granted: "Location allowed — you can show the map.",
    prompt: "Location not decided yet — show an Enable button.",
    denied: "Location blocked — explain how to re-enable in settings."
  };
  return messages[state] || ("Unknown state: " + state);
}

geoStatusMessage().then((msg) => console.log(msg));

Location not decided yet — show an Enable button.
(exact line depends on your permission state)

async function watchGeoPermission() {
  if (!navigator.permissions) {
    console.log("Permissions API missing");
    return;
  }
  const status = await navigator.permissions.query({ name: "geolocation" });
  console.log("initial: " + status.state);
  status.addEventListener("change", () => {
    console.log("changed: " + status.state);
  });
}

watchGeoPermission();

initial: prompt
(then "changed: …" if you update site permissions)

async function queryPermission(name) {
  if (!navigator.permissions || !navigator.permissions.query) {
    return { ok: false, reason: "api-missing" };
  }
  try {
    const status = await navigator.permissions.query({ name });
    return { ok: true, name, state: status.state };
  } catch (err) {
    return {
      ok: false,
      reason: "query-failed",
      message: String(err && err.message ? err.message : err)
    };
  }
}

queryPermission("geolocation").then((info) => {
  console.log(JSON.stringify(info));
});

{"ok":true,"name":"geolocation","state":"prompt"}
(or a failure object if the name is unsupported)

🚀 Common Use Cases

• Maps / store finders — show Enable Location only when state is prompt.
• Camera / mic apps — check status before opening a capture UI (where supported).
• Notification opt-in — avoid asking again after denied.
• Settings panels — display current permission state with clear next steps.
• Diagnostics — include permission states in support debug reports.

📝 Notes

• Baseline Widely available (MDN, since September 2022).
• Not Deprecated, Experimental, or Non-standard — no status banner required.
• Read-only; use Permissions.query() on the returned object.
• Supported permission name values vary by browser — wrap queries in try/catch.
• Related: geolocation, pdfViewerEnabled, mediaDevices, Window.

💡 Best Practices