1. Web
  2. Web APIs
  3. Navigator
  4. unregisterProtocolHandler()

Navigator: unregisterProtocolHandler() method

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The Navigator method unregisterProtocolHandler() removes a protocol handler for a given URL scheme.

This method is the inverse of registerProtocolHandler().

Syntax

js
unregisterProtocolHandler(scheme, url)

Parameters

scheme

A string containing the permitted scheme in the protocol handler that will be unregistered. For example, you can unregister the handler for SMS text message links by passing the "sms" scheme.

url

A string containing the URL of the handler. This URL should match the one that was used to register the handler (e.g., it must include %s).

Return value

None (undefined).

Exceptions

SecurityError DOMException

The user agent blocked unregistration. This might happen if:

  • The scheme (protocol) is invalid, such as a scheme the browser handles itself (https:, about:, etc.)
  • The handler URL's origin does not match the origin of the page calling this API.
  • The browser requires that this function is called from a secure context.
  • The browser requires that the handler's URL be over HTTPS.
SyntaxError DOMException

The %s placeholder is missing from the handler URL.

Permitted schemes

For security reasons, unregisterProtocolHandler() restricts which schemes can be unregistered.

A custom scheme may be unregistered as long as:

  • The custom scheme's name begins with web+
  • The custom scheme's name includes at least 1 letter after the web+ prefix
  • The custom scheme has only lowercase ASCII letters in its name.

For example, web+burger, as shown in the Example below.

Otherwise, the scheme must be one of the following:

  • bitcoin
  • ftp
  • ftps
  • geo
  • im
  • irc
  • ircs
  • magnet
  • mailto
  • matrix
  • mms
  • news
  • nntp
  • openpgp4fpr
  • sftp
  • sip
  • sms
  • smsto
  • ssh
  • tel
  • urn
  • webcal
  • wtai
  • xmpp

Examples

If your site is burgers.example.com, and you have a web+burger: scheme, you can unregister the handler for it like so:

js
navigator.unregisterProtocolHandler(
  "web+burger",
  "https://burgers.example.com/?burger=%s",
);

This script must be run from the same origin as the handler URL (so any page at https://burgers.example.com), and the handler URL must be http or https.

Specifications

Specification
HTML
# dom-navigator-unregisterprotocolhandler-dev

Browser compatibility

Help improve MDN

Learn how to contribute

This page was last modified on by MDN contributors.

View this page on GitHub • Report a problem with this content