JavaScript Navigator registerProtocolHandler() Method

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

Definition

navigator.registerProtocolHandler(scheme, url) lets a site register itself as a handler for a URL scheme such as mailto:, tel:, or a custom web+… scheme (MDN). Later, matching links can open your HTTPS template page with the original link substituted for %s.

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

Syntax

Call navigator.registerProtocolHandler. Start with this line.

JavaScript
navigator.registerProtocolHandler(scheme, url)
CallWhat it does
navigator.registerProtocolHandler(scheme, url)Primary signature.
navigator.registerProtocolHandler(...)Call with the arguments your case needs.

Built into the browser. Call registerProtocolHandler(...) on a Navigator — no import required.

Library declarations
JavaScript
navigator.registerProtocolHandler(scheme, url)

Parameters

ParameterDescription
schemeRequired. Protocol to handle (allowed list or web+)
urlRequired. HTTPS same-origin template with %s

Return Value

Return ValueDescription
*Always undefined (MDN)

JavaScript Examples

Example 1 — Feature-Detect First

Limited availability + secure context — check before calling.

JavaScript
const supported =
  typeof navigator.registerProtocolHandler === "function";

console.log("API:", supported ? "available" : "missing");
console.log("secure:", window.isSecureContext);
console.log("origin:", location.origin);
Try It Yourself

How It Works

  1. Test the type so missing APIs do not throw.
  2. Check secure context — HTTPS or localhost (MDN).
  3. Note the origin — the template URL must match it.
  4. Skip registration when either check fails.

Example 2 — mailto Handler Pattern (MDN)

Build a same-origin HTTPS template and show how %s is filled.

JavaScript
const template = location.origin + "/mail?to=%s";
const clicked = "mailto:[email protected]";

// What the browser does after a successful registration:
const opened = template.replace("%s", encodeURIComponent(clicked));

console.log("template:", template);
console.log("opened:", opened);

// Real registration (user gesture + HTTPS + same origin):
// navigator.registerProtocolHandler("mailto", template);
Try It Yourself

How It Works

  1. Template includes %s. Missing it → SyntaxError (MDN).
  2. Same origin + https. Required for the handler URL (MDN).
  3. Browser fills %s with the activated link (escaped).
  4. Your page parses the query and opens compose UI.

Example 3 — Custom web+ Scheme

MDN: custom schemes must start with web+ and use lowercase ASCII letters.

JavaScript
function isCustomWebScheme(scheme) {
  return /^web\+[a-z]+$/.test(scheme);
}

const scheme = "web+burger";
const template = location.origin + "/?burger=%s";
const link = "web+burger:cheeseburger";

console.log("valid scheme:", isCustomWebScheme(scheme));
console.log("navigates to:", template.replace("%s", encodeURIComponent(link)));

// navigator.registerProtocolHandler(scheme, template);
Try It Yourself

How It Works

  1. Prefix web+. Required for custom schemes (MDN).
  2. Lowercase letters only after the prefix.
  3. Same %s rules as mailto / listed schemes.
  4. User confirmation may still appear before navigation.
Compatibility

Browser Support

navigator.registerProtocolHandler() has Limited availability (not Baseline) on MDN. It requires a secure context. Not Deprecated, Experimental, or Non-standard — always feature-detect.

✓ Limited availability · Not Baseline

Navigator.registerProtocolHandler()

Register URL scheme handlers with an HTTPS %s template. Support varies by browser.

Limited Not Baseline
Google Chrome Supported (secure context)
Yes
Microsoft Edge Supported (Chromium)
Yes
Opera Supported where Chromium does
Yes
Mozilla Firefox Supported (check version)
Yes
Apple Safari Limited / check support
Partial
Internet Explorer Not supported
No
registerProtocolHandler() Feature-detect

Bottom line: Use on HTTPS, include %s, same origin. See the MDN registerProtocolHandler() reference.

Frequently Asked Questions

MDN: it lets a website register its ability to open or handle particular URL schemes (protocols). When the user activates a matching link, the browser fills your HTTPS template URL’s %s placeholder and navigates there.
No. MDN does not mark it Deprecated, Experimental, or Non-standard. It is Limited availability (not Baseline) and requires a secure context. Always feature-detect.
An https URL of the same origin as the registering page, containing the %s placeholder that the browser replaces with the escaped URL being handled (MDN).
No. Schemes the browser already handles itself are blocked (SecurityError). Use an allowed scheme from the HTML list, or a custom scheme that begins with web+ and uses lowercase ASCII letters.
Often yes — either when registering or when the user first activates a matching link. Call registration from a clear user gesture (for example a button click).
SecurityError when the scheme or origin/https rules fail, and SyntaxError when %s is missing from the template URL. Feature-detect and wrap calls in try/catch.

Next: requestMediaKeySystemAccess()

Continue with the next Navigator method in the tutorial series.

requestMediaKeySystemAccess() →

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)

20 people found this page helpful

JavaScript Navigator javaEnabled() Method JavaScript Navigator requestMediaKeySystemAccess() Method