Progressive Share Button

The Progressive Share Button web component is a simple way to add a share button to your web page. The button will only be displayed if the browser supports the Web Share API.

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.

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.

Basic Usage

The most basic usage of the component is to pass the URL to be shared. The component will render a share icon that will open the native share dialog when clicked.

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

This will render one of the following, depending on the device and browser. This example shows the Windows sharing icon, the Android sharing icon, and the iOS sharing icon.

Installation as a module

Run the following command to install it.

npm install progressive-share-button

main.js, if installed with npm

import { ProgressiveShareButton } from 'progressive-share-button';
customElements.define('progressive-share-button', ProgressiveShareButton);

CDN

https://unpkg.com/ info to come

<script src="https://unpkg.com/TBD/progressive-share-button"></script>

Customizing the Component

The component accepts the following attributes:

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.

shareButton

The shareButton part is the button that is displayed when the Web Share API is supported. The button is a button element. The button has the following default styles:

button {
  background: none;
  border: none;
  padding: 1px 2px 1px 2px;
  margin: 0;
  cursor: pointer;
}

shareIcon

The shareIcon part is the icon that is displayed when the Web Share API is supported. The icon is an svg element. The icon has the following default styles:

svg {
  width: 24px;
  height: 24px;
  fill: currentColor;
  vertical-align: bottom;
}

Usage Examples

Basic Usage

As shown earlier, the most basic usage of the component is to pass the URL to be shared.

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

Usage with Text

You can replace the share icon with text by inserting text into the component's slot. The following example replaces the share icon with the text "Share this link". The text is styled with the text-share-example-1 class using using the ::part() pseudo-element named shareButton.

<progressive-share-button url="https://example.com" class="text-share-example-1">Share this link</progressive-share-button>

<style>
progressive-share-button.text-share-example-1::part(shareButton) {
  font-size: 1rem;
  text-decoration: underline;
  color: blue;
}
</style>

Advanced Usage with Options

In the following example,

<progressive-share-button
  title="Progressive Share Button Web Component"
  text="Check out this cool web component that creates a share button that will only be displayed if the browser supports the Web Share API."
  url="https://example.com"
  smart-share=1
  icon-size="20"
  debug=0
  class="text-share-example-2"
/>

<style>
progressive-share-button.text-share-example-2::part(shareIcon) {
  font-size: 1rem;
  text-decoration: underline;
  color: blue;
}

Why use smart-share

The Web Share API requires that the data to be shared be passed as an object with the following optional properties:

• title
• text
• url

The Progressive Share Button web component by default simply passes your data to the Web Share API, like this:

{
  title: 'Example Page',
  text: 'This is an example page.',
  url: 'https://example.com'
}

The problem is that when multiple properties are passed as separate properties what actually gets shared doesn't always include all the pieces of data you pass into the API. Some devices and applications receiving the data object will only share a single property, most often the URL in my tests.

If have smart-share set to true, the component will concatenate all of the data into a single string and pass it to the Web Share API as text. The title and text will have a period added at the end of the string if it is not present. This will allow the data to be shared on any device or application that supports sharing text. The data will be shared as a single string, like this:

{
  text: 'Example Page. This is an example page. https://example.com'
}

The following link lets you test the Web Share API on your devices to make a more informed decision as to what option works best for your use case.

https://w3c.github.io/web-share/demos/share-files.html

Demo

Demo to come.

https://johnfmorton.github.io/progressive-share-button/

License

MIT

Author

John F. Morton