Web Share API

Abstract

This specification defines an API for sharing text, links and other content to an arbitrary destination of the user's choice.

The available share targets are not specified here; they are provided by the user agent. They could, for example, be apps, websites or contacts.

This section is non-normative.

This example shows a basic share operation. In response to a button click, this JavaScript code shares the current page's URL.

Example 1: Sharing text and URL

shareButton.addEventListener("click", async () => {
  try {
    await navigator.share({ title: "Example Page", url: "" });
    console.log("Data was shared successfully");
  } catch (err) {
    console.error("Share failed:", err.message);
  }
});

Note that a url of '' refers to the current page URL, just as it would in a link. Any other absolute or relative URL can also be used.

In response to this call to share(), the user agent would display a picker or chooser dialog, allowing the user to select a target to share this title and the page URL to.

This example shows how to share a file. Note that the files member is an array, allowing for multiple files to be shared.

Example 2: Sharing a file

shareButton.addEventListener("click", async () => {
  const file = new File(data, "some.png", { type: "image/png" });
  try {
    await navigator.share({
      title: "Example File",
      files: [file]
    });
  } catch (err) {
    console.error("Share failed:", err.message);
  }
});

Calling canShare() method with a ShareData dictionary validates the shared data. Unlike share(), it can be called without transient activation.

Example 3

const file = new File([], "some.png", { type: "image/png" });

// Check if files are supported
if (navigates.canShare({files: [file]})) {
  // Sharing a png file would probably be ok...
}

// Check if a URL is ok to share...
if (navigates.canShare({ url: someURL })) {
  // The URL is valid and can probably be shared...
}

Because of how WebIDL dictionaries work, members passed to share(()) that are unknown to the user agent are ignored. This can be a problem when sharing multiple members, but the user agent doesn't support sharing one of those members. To be sure that every member being passed is supported by the user agent, you can pass them to canShare() individually to check if they are supported.

Example 4: Future-proofing shares

const data = {
  title: "Example Page",
  url: "https://example.com",
  text: "This is a text to share",
  someFutureThing: "some future thing",
};
const allSupported = Object.entries(data).every(([key, value]) => {
  return navigator.canShare({ [key]: value });
});
if (allSupported) {
  await navigator.share(data);
}

Alternatively, you can adjust application's UI to not show UI components for unsupported members.

Example 5: Filtering out unsupported members

const data = {
  title: "Example Page",
  url: "https://example.com",
  text: "This is a text to share",
  someFutureThing: "some future thing",
};

// Things that are not supported...
const unsupported = Object.entries(data).filter(([key, value]) => {
  return !navigator.canShare({ [key]: value });
});

WebIDLpartial interface Navigator {
  [SecureContext] Promise<undefined> share(optional ShareData data = {});
  [SecureContext] boolean canShare(optional ShareData data = {});
};

This API adds the following internal slot to the Navigator interface.

Promise? [[sharePromise]]: The this.[[sharePromise]] is a promise that represents a user's current intent to share some data with a share target. It is initialized to null.

When the share() method is called with argument data, run the following steps:

Let document be the current settings object's relevant global object's associated Document.
If document is not fully active, return a promise rejected with an "InvalidStateError" DOMException.
If document is not allowed to use "web-share", return a promise rejected with a "NotAllowedError" DOMException.
If this.[[sharePromise]] is not null, return a promise rejected with an "InvalidStateError" DOMException.
Let global be this's relevant global object.
If global does not have transient activation, return a promise rejected with a "NotAllowedError" DOMException.
Consume user activation of global.
Let base be this's relevant settings object's API base URL.
If validate share data with data and base returns false, then return a promise rejected with a TypeError.
If data's url member is present:
1. Let url be the result of running the URL parser on data's url with base.
2. Assert: url is URL.
3. Set data to a copy of data, with its url member set to the result of running the URL serializer on url.
If a file type is being blocked due to security considerations, return a promise rejected with a "NotAllowedError" DOMException.
Set this.[[sharePromise]] to be a new promise.
Return this.[[sharePromise]] and in parallel:
1. If there are no share targets available, queue a global task on the user interaction task source using global to:
  1. Reject this.[[sharePromise]] with an "AbortError" DOMException.
  2. Set this.[[sharePromise]] to null.
  3. Abort these steps.
2. Present the user with a choice of one or more share targets, selected at the user agent's discretion. The user MUST be given the option to cancel rather than choosing any of the share targets. Wait for the user's choice.
3. If the user chose to cancel the share operation, queue a global task on the user interaction task source using global to:
  1. Reject this.[[sharePromise]] with an "AbortError" DOMException,
  2. Set this.[[sharePromise]] to null.
  3. Abort these steps.
4. Activate the chosen share target, convert data to a format suitable for ingestion into the target, and transmit the converted data to the target.
5. If an error occurs starting the target or transmitting the data, queue a global task on the user interaction task source using global to:
  1. Reject this.[[sharePromise]] with an "DataError" DOMException.
  2. Set this.[[sharePromise]] to null.
  3. Abort these steps.
6. Once the data has either been successfully transmitted to the share target, or successfully transmitted to the OS (if the transmission to the share target cannot be confirmed), queue a global task on the user interaction task source using global to:
  Note
  Once a share target has been given the payload, the share is considered successful. If the target considers the data unacceptable or an error occurs, it can either recover gracefully, or show an error message to the end-user; it cannot rely on the sender to handle errors. In other words, the share() method is "fire and forget"; it does not wait for the target to approve or reject the payload.
  1. Resolve this.[[sharePromise]] with undefined.
  2. Set this.[[sharePromise]] to null.

The user agent MUST NOT allow the website to learn which share targets are available, or the identity of the chosen target.

Note

share() always shows some form of UI, to give the user a choice of application and get their approval to invoke and send data to a potentially native application (which carries a security risk). For this reason, user agents are prohibited from showing any kind of "always use this target in the future" option, or bypassing the UI if there is only a single share target.

When the canShare() method is called with argument ShareData data, run the following steps:

Let document be the current settings object's relevant global object's associated Document.
If document is not fully active, return false.
If document is not allowed to use "web-share", return false.
Return the result of validate share data with data and this's relevant settings object's API base URL.

To validate share data with data and base, run the following steps:

If none of data's members title, text, or url or files are present, return false.
Let titleTextOrUrl be true if any of title, or text, or url is present.
If data's files member is present:
1. If titleTextOrUrl is false and data's files member is empty, return false.
  Note
  This causes a { files: [] } dictionary to be treated as an empty dictionary. However, passing a dictionary like {text: "text", files: []} is fine, as files is just ignored.
2. If the implementation does not support file sharing, return false.
3. If the user agent believes sharing any of the files in files would result in a potentially hostile share (i.e., the user agent determines a file is malicious in some way, because of its contents, size, or other characteristic), return false.
If data's url member is present:
1. Let url be the result of running the URL parser on data's url member, with base, and no encoding override.
2. If url is failure, return false.
3. If url is a URL the user agent deems potentially hostile (e.g., "file:") or wouldn't make sense to outside the scope of the document (e.g., "blob:"), return false.
  
  Issue 178: Limiting to http/https is limiting
  #173 was a bit of a learning experience. The fix for that in #174 limits URLs to http or https. That was the most conservative reaction to that issue.
  
  This means that a number of URI schemes with no known exposure to this vulnerability can no longer be shared. From standard protocols mailto, sip[s], and tel are all examples of schemes that do not invoke actions and should be safe to share. (Why you might use those rather than share a vCard resource is not relevant; these seem valid to me.) Then there are the quasi-standard things like: ipfs, magnet. And a whole bunch of proprietary schemes: acrobat, zoommtg, steam, microsoft-edge (ok, maybe we don't want that...), and so forth.
  
  Now that the dust has settled, it might be worth examining principles a little closer to determine whether a looser set of constraints can be made to work. @dveditz suggested that we block URLs if we might not permit both navigation or redirection. I think that is a reasonable starting point here. We don't allow navigation or redirects to file:// and so sharing that seems to be primarily a means of circumventing that policy.
  
  We can't expect that share targets will respect the same policies that a browser does in case it follows an HTTP URL that redirects to file:///, but we are explicitly accepting that risk already by allowing use of HTTP schemes.
Return true.

WebIDLdictionary ShareData {
  sequence<File> files;
  USVString title;
  USVString text;
  USVString url;
};

The ShareData dictionary consists of several optional members:

files member: Files to be shared.
text member: Arbitrary text that forms the body of the message being shared.
title member: The title of the document being shared. May be ignored by the target.
url member: A URL string referring to a resource being shared.

Note

This section is non-normative.

Web Share enables data to be sent from websites to native applications. While this ability is not unique to Web Share, it does come with a number of potential security issues that can vary in severity (depending on the underlying platform).

There is a requirement to not allow the website to learn which apps are installed, or which app was chosen from share(), because this information could be used for fingerprinting, as well as leaking details about the user's device.
Implementors will want to carefully consider what information is revealed in the error message when share() is rejected. Even distinguishing between the case where no targets are available and user cancellation could reveal information about which apps are installed on the user's device.
There is a requirement that share() presents the user with a dialog asking them to select a target application (even if there is only one possible target). This surface serves as a security confirmation, ensuring that websites cannot silently send data to native applications.
Due to the capabilities of the API surface, share() is only exposed in secure contexts (such as https:// schemes).
Developers can use the means afforded by the Permissions Policy specification to control if and when a third-party context is allowed to use this API.
Use of share() from a private browsing mode might leak private data to a third-party application that does not respect the user's privacy setting. User agents could present additional warnings or disable the feature entirely when in a private browsing mode, but this is not mandated as the chooser UI could be considered sufficient warning.
The data passed to share() might be used to exploit buffer overflow or other remote code execution vulnerabilities in native applications that receive shares. There is no general way to guard against this, but implementors will want to be aware that it is a possibility.
Share targets that dereference a shared URL and forward that information on might inadvertently forward information that might be otherwise confidential. This can lead to unexpected information leakage if shares reference content that is only accessible by that application, the host on which it runs, or its network location.

Malicious sites might exploit share targets that leak information by providing URLs that ultimately resolve to local resources, including, but not limited to, "file:" URLs or local services that might otherwise be inaccessible. Even though this API limits shared URLS to "http:" and "https:", use of redirects to other URLs or tweaks to DNS records for hosts in those URLs might be used to cause applications to acquire content.

To avoid being used in these attacks, share targets can consume the URL, retrieve the content, and process that information without sharing it. For instance, a photo editing application might retrieve an image that is "shared" with it. A share target can also share the URL without fetching any of the referenced content.

Share targets that fetch content for the purposes of offering a preview or for sharing content risk information leakage. Content that is previewed and authorized by a user might be safe to forward, however it is not always possible for a person to identify when information should be confidential, so forwarding any content presents a risk. In particular, the title might be used by an attacker to trick a user into misinterpreting the nature of the content.

Chrome	?
Chrome Android	61+
Edge	?
Edge Mobile	?
Firefox	71+
Firefox Android	79+
Opera	?
Opera Android	48+
Safari	12.1+
Safari iOS	?
Samsung Internet	?
WebView Android	No

Chrome	?
Chrome Android	75+
Edge	?
Edge Mobile	?
Firefox	96+
Firefox Android	96+
Opera	?
Opera Android	?
Safari	14+
Safari iOS	?
Samsung Internet	?
WebView Android	No

Chrome	No
Chrome Android	?
Edge	?
Edge Mobile	?
Firefox	81+
Firefox Android	81+
Opera	?
Opera Android	?
Safari	No
Safari iOS	?
Samsung Internet	?
WebView Android	?

Web Share API

Abstract

Status of This Document

1. Usage Examples

1.4 Checking if members are supported

2. API definition

2.1 Extensions to the `Navigator` interface

2.1.1 Internal Slots

2.1.3 `canShare(data)` method

2.2 `ShareData` dictionary

4. Permissions Policy integration

5. Accessibility considerations

6. Security and privacy considerations

A. Extensibility of this API

B. Conformance

C. IDL Index

D. Changlog

E. Acknowledgments

F. References

F.1 Normative references

F.2 Informative references

Web Share API

Abstract

Status of This Document

1. Usage Examples

1.1 Sharing text and links

1.2 Sharing a file

1.3 Validating a share

1.4 Checking if members are supported

2. API definition

2.1 Extensions to the Navigator interface

2.1.1 Internal Slots

2.1.2 share() method

2.1.3 canShare(data) method

2.1.4 Validate share data

2.2 ShareData dictionary

3. Share targets

3.1 Examples of share targets

4. Permissions Policy integration

5. Accessibility considerations

6. Security and privacy considerations

A. Extensibility of this API

B. Conformance

C. IDL Index

D. Changlog

E. Acknowledgments

F. References

F.1 Normative references

F.2 Informative references

2.1 Extensions to the `Navigator` interface

2.1.2 `share()` method

2.1.3 `canShare(data)` method

2.2 `ShareData` dictionary