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 is a work in progress. Wide review and feedback welcome.

Usage Examples

This example shows a basic share operation. In response to a button click, this JavaScript code shares the current page's 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 {{ShareData/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 {{Navigator/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.

API definition

Extensions to the `Navigator` interface 

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

User agents that do not support sharing SHOULD NOT expose {{Navigator/share()}} on the {{Navigator}} interface.

The above statement is designed to permit feature detection. If {{Navigator/share()}} is present, there is a reasonable expectation that it will work and present the user with at least one share target. Clients can use the presence or absence of this method to determine whether to show UI that triggers its use.

Internal Slots

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

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

share() method

When the {{Navigator/share()}} method is called with argument |data:ShareData|, run the following steps:

  1. If the current settings object's responsible document is not allowed to use the "[=web-share-feature|web-share=]" permission, return [=a promise rejected with=] with a {{"NotAllowedError"}} {{DOMException}}.
  2. If {{[[sharePromise]]}} is not `null`, return a promise rejected with {{InvalidStateError}}.
  3. Let |window| be [=relevant global object=] of [=this=].
  4. If |window| does not have [=transient activation=], return [=a promise rejected with=] with a {{"NotAllowedError"}} {{DOMException}}.
  5. [=Consume user activation=] of |window|.
  6. If none of |data|'s members {{ShareData/title}}, {{ShareData/text}}, or {{ShareData/url}} or {{ShareData/file}} are present, return a promise rejected with a {{TypeError}}.
  7. If |data|'s {{ShareData/files}} member is present:
    1. If |data|'s {{ShareData/files}} member is empty, or if the implementation does not support file sharing, return a promise rejected with a {{TypeError}}, and abort these steps.
  8. If |data|'s {{ShareData/url}} member is present:
    1. Let |base:URL| be the [=this=] value's relevant settings object's [=environment settings object/api base URL=].
    2. Let |url:URL| be the result of running the URL parser on |data|'s {{ShareData/url}} with |base|.
    3. If |url| is failure, return a promise rejected with {{TypeError}}.
    4. If |url|'s [=URL/scheme=] is not "http" or "https", return a promise rejected with {{TypeError}}.
    5. Set |data| to a copy of |data|, with its {{ShareData/url}} member set to the result of running the URL serializer on |url|.
  9. If a file type is being blocked due to security considerations, return a promise rejected with with a {{"NotAllowedError"}} {{DOMException}}.
  10. Set {{[[sharePromise]]}} to be a new promise.
  11. Return {{[[sharePromise]]}} and in parallel:
    1. If there are no share targets available:
      1. Reject {{[[sharePromise]]}} with an {{"AbortError"}} {{DOMException}}.
      2. Set {{[[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:
      1. Reject {{[[sharePromise]]}} with an {{"AbortError"}} {{DOMException}},
      2. Set {{[[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:
      1. Reject {{[[sharePromise]]}} with an {{"DataError"}} {{DOMException}}.
      2. Set {{[[sharePromise]]}} to `null`.
      3. Abort these steps.
    6. Once the data has been successfully transmitted to the target, resolve {{[[sharePromise]]}} with `undefined`.
    7. Set {{[[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.

{{Navigator/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.

`ShareData` dictionary 

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

The ShareData dictionary consists of several optional members:

files member
Files to be shared.
title member
The title of the document being shared. May be ignored by the target.
text member
Arbitrary text that forms the body of the message being shared.
url member
A URL string referring to a resource being shared.
These members are {{USVString}} (as opposed to {{DOMString}}) because they are not allowed to contain surrogate code points. Among other things, this means that the user agent can serialize them into any Unicode encoding, such as UTF-8, without change or loss of data or the generation of replacement characters.
The {{ShareData/url}} member can contain a relative-URL string. In this case, it will be automatically resolved relative to the current page location, just like a {{HTMLBaseElement/href}} on an [^a^] element, before being given to the share target.

Share targets

A share target is the abstract concept of a destination that the user agent will transmit the share data to. What constitutes a share target is at the discretion of the user agent.

A share target might not be directly able to accept a {{ShareData}} (due to not having been written with this API in mind). However, it MUST have the ability to receive data that matches some or all of the concepts exposed in {{ShareData}}. To convert data to a format suitable for ingestion into the target, the user agent SHOULD map the members of {{ShareData}} onto equivalent concepts in the target. It MAY discard or combine members if necessary. The meaning of each member of the payload is at the discretion of the share target.

Mapping the {{ShareData}} to the share target's (or operating system's) native format can be tricky as some platforms will not have an equivalent set of members. For example, if the target has a "text" member but not a "URL" member (as is the case on Android), one solution is to concatenate both the {{ShareData/text}} and {{ShareData/url}} members of {{ShareData}} and pass the result in the "text" member of the target.

Each share target MAY be made conditionally available depending on the {{ShareData}} payload delivered to the {{Navigator/share()}} method.

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 {{Navigator/share()}} method is "fire and forget"; it does not wait for the target to approve or reject the payload.

Examples of share targets

The list of share targets can be populated from a variety of sources, depending on the user agent and host operating system. For example:

There is an attempt to standardize the registration of websites to receive share data for that final use case; see Web Share Target.

In some cases, the host operating system will provide a sharing or intent system similar to Web Share. In these cases, the user agent can simply forward the share data to the operating system and not talk directly to native applications.

Permission Policy integration

This specification defines a policy-controlled permission identified by the string "web-share". Its default allowlist is '`self`'.

A document’s permission policy determines whether a {{Navigator/share()}} call immediately rejects with a {{"NotAllowedError"}} {{DOMException}}.

Accessibility considerations

When this specification is used to present information in the user interface, implementors will want to follow the OS level accessibility guidelines for the platform.

Security and privacy considerations

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).

Extensibility of this API

The Web Share API is designed to be extended in the future by way of new members added to the {{ShareData}} dictionary, to allow both sharing of new types of data (e.g., images) and strings with new semantics (e.g. author).

This doesn't mean user agents can add whatever members they like. It means that new members can be added to the standard in the future.

The three members {{ShareData/title}}, {{ShareData/text}}, and {{ShareData/url}}, are part of the base feature set, and implementations that provide {{Navigator/share()}} need to accept all three. Any new members that are added in the future will be individually feature-detectable, to allow for backwards-compatibility with older implementations that don't recognize those members. These new members might also be added as optional "MAY" requirements.

There is an open discussion about how to provide feature-detection for dictionary members. Web Share will use the mechanism produced by that discussion.

The {{Navigator/share()}} method returns a rejected promise with a {{TypeError}} if none of the specified members are present. The intention is that when a new member is added, it will also be added to this list of recognized members. This is for future-proofing implementations: if a web site written against a future version of this spec uses only new members (e.g., `navigator.share({image: x})`), it will be valid in future user agents, but a {{TypeError}} on user agents implementing an older version of the spec. Developers will be asked to feature-detect any new members they rely on, to avoid having errors surface in their program.

Editors of this spec will want to carefully consider the genericity of any new members being added, avoiding members that are closely associated with a particular service, user agent or operating system, in favour of members that can potentially be applied to a wide range of platforms and targets.

Changlog

Acknowledgments

Thanks to the Web Intents team, who laid the groundwork for the web app interoperability use cases. In particular, Paul Kinlan, who did a lot of early advocacy for Web Share.