Progressive Share Button

The Progressive Share Button web component is a simple way to add a share button to your web page that will show the user the OS native share options using the Web Share API. The "progressive" part of the name comes from the fact that the component will only display the share button if the browser supports the Web Share API. If the browser does not support the Web Share API, the component will not display anything.

The web component is a wrapper around the Web Share API that attempts to display a share icon appropriate to the user's device with icons that will be recognizable to iOS/Mac, Android and Windows. If the device type can't be determined, the component will display a Windows share icon.

Demo

Check out the demo page, https://johnfmorton.github.io/progressive-share-button/, to see the component in action.

Basic Usage

The most basic usage of the component is to use no attributes. The component will share the current page's URL.

<progressive-share-button />

You may also pass the URL to be shared. The component will share the URL that has been specified.

<progressive-share-button url="https://example.com" />

This will render one of the following, depending on the device and browser.

This example image below shows the Windows sharing icon, the Android sharing icon, and the iOS/Mac sharing icon.

Limitations

The Web Share API, while still in draft, has wide support on mobile. Desktop support is decent on Windows. Mac support works in Safari, but lags on third-party browsers. Check caniuse/web-share for the most up-to-date information on its progress.

The component will only display the share button if the browser supports the Web Share API. If the browser does not support the Web Share API, the component will not display anything.

Progressive Share Button does not support the sharing of files.

Installation as a module

The component is available as an npm module. Run the following command to install it.

npm install progressive-share-button

main.js, if installed with npm

// Import the component
import { ProgressiveShareButton } from 'progressive-share-button';
// Initialize the component
ProgressiveShareButton();

Customizing the component name

If you want to customize the component name, you can import the element class directly and register it with a different name. Take note of the curly braces used in the import statement. This is a named import.

import { ProgressiveShareButtonClass } from 'progressive-share-button';
// Initialize the component
customElements.define('my-share-button', ProgressiveShareButtonClass);

CDN

You can also use the component directly from a CDN. The component is available on unpkg. The following example shows how to use the component from unpkg. Note the use of ?module at the end of the URL in the import statement.

<script type="module">
  import { ProgressiveShareButton } from 'https://unpkg.com/progressive-share-button?module';
  // Initialize the component
  ProgressiveShareButton();
</script>
<progressive-share-button title="Hello World!" url="https://example.com" debug="true"></progressive-share-button>

Typescript support

The component is written in Typescript and includes type definitions. If you are using Typescript, you can import the component directly into your project and see code completion hints. See the Custom events section for more information about using the custom event type definitions.

Customizing the Component

The component accepts the following attributes:

Attributes	Type	Default	Description
title	string	null	The title of the page to be shared.
text	string	null	The text string to be shared.
url	string	null	The URL to be shared.
smart-share	boolean	false	Accepts 0, false, 1, or true. If true, the component concatenate the title, text, and url into a single string. See the Why use smart-share section below for more information.
icon-size	string or int	24	The size of the SVG share icon. The icon is rendered in a square. If an integer is passed, the component assumes the value is given in pixels, 24 becomes 24px, but you may also pass a string with a valid CSS size, like 1rem.
os	string or null	auto	Set to android, ios, or windows to override the automatic detection of the user's operating system. This setting is useful during development with the debug option. For production, leaving it unset or set to auto will provide the best user experience for end users.
debug	boolean	false	Accepts 0, false, 1, or true. If true is passed, the share icon will be displayed even if the Web Share API is not supported in the browser. The share behavior will not open the share dialog but, but instead will pass the data to be shared to the console for debugging. No custom events will be fired.

Styling

The component uses the Shadow DOM to encapsulate the styles. This means that the styles are not inherited by the parent page. To style the component, you must use the ::part() pseudo-element. There are two parts that can be styled: shareButton and shareIcon.

The basic Shadow DOM strutcture of the component is as follows:

This is the beginning of the README. Read the rest at the original. Read the full README ↗