docs.rodeo

MDN Web Docs mirror

Navigator: share() method

{{APIRef("Web Share API")}} {{securecontext_header}} 

The share() method of the {{domxref("Navigator")}}  interface invokes the native sharing mechanism of the device to share data such as text, URLs, or files. The available share targets depend on the device, but might include the clipboard, contacts and email applications, websites, Bluetooth, etc.

The method resolves a {{jsxref("Promise")}}  with undefined. On Windows this happens when the share popup is launched, while on Android the promise resolves once the data has successfully been passed to the share target.

The Web Share API is gated by the web-share permission policy. The share() method will throw exceptions if the permission is supported but has not been granted.

Syntax

share(data)

Parameters

Return value

A {{jsxref("Promise")}}  that resolves with undefined, or rejected with one of the Exceptions given below.

Exceptions

The {{jsxref("Promise")}}  may be rejected with one of the following DOMException values:

Shareable file types

The following is a list of usually shareable file types. However, you should always test with {{domxref("navigator.canShare()")}}  if sharing would succeed.

Security

This method requires that the current document have the web-share Permissions Policy and {{Glossary("transient activation")}} . (It must be triggered off a UI event like a button click and cannot be launched at arbitrary points by a script.) Further, the method must specify valid data that is supported for sharing by the native implementation.

Examples

Sharing a URL

The example below shows a button click invoking the Web Share API to share MDN’s URL. This is taken from our Web share test (see the source code).

HTML

The HTML just creates a button to trigger the share, and a paragraph in which to display the result of the test.

<p><button>Share MDN!</button></p>
<p class="result"></p>

JavaScript

const shareData = {
  title: "MDN",
  text: "Learn web development on MDN!",
  url: "https://developer.mozilla.org",
};

const btn = document.querySelector("button");
const resultPara = document.querySelector(".result");

// Share must be triggered by "user activation"
btn.addEventListener("click", async () => {
  try {
    await navigator.share(shareData);
    resultPara.textContent = "MDN shared successfully";
  } catch (err) {
    resultPara.textContent = `Error: ${err}`;
  }
});

Result

Click the button to launch the share dialog on your platform. Text will appear below the button to indicate whether the share was successful or provide an error code.

{{EmbedLiveSample('Sharing a URL','','','','','','web-share')}} 

Sharing files

To share files, first test for and call {{domxref("navigator.canShare()")}} . Then include the list of files in the call to navigator.share().

HTML

<div>
  <label for="files">Select images to share:</label>
  <input id="files" type="file" accept="image/*" multiple />
</div>
<button id="share" type="button">Share your images!</button>
<output id="output"></output>

JavaScript

Note that the data object passed to the navigator.canShare() only includes the files property, as the title and text shouldn’t matter.

const input = document.getElementById("files");
const output = document.getElementById("output");

document.getElementById("share").addEventListener("click", async () => {
  const files = input.files;

  if (files.length === 0) {
    output.textContent = "No files selected.";
    return;
  }

  // feature detecting navigator.canShare() also implies
  // the same for the navigator.share()
  if (!navigator.canShare) {
    output.textContent = `Your browser doesn't support the Web Share API.`;
    return;
  }

  if (navigator.canShare({ files })) {
    try {
      await navigator.share({
        files,
        title: "Images",
        text: "Beautiful images",
      });
      output.textContent = "Shared!";
    } catch (error) {
      output.textContent = `Error: ${error.message}`;
    }
  } else {
    output.textContent = `Your system doesn't support sharing these files.`;
  }
});

Result

{{EmbedLiveSample('Sharing files')}} 

Specifications

{{Specifications}} 

Browser compatibility

{{Compat}} 

See also

In this article

View on MDN