dabolus/share-menu

A complete and simple to use share menu.

<share-menu>

Demo and API docs

A complete and simple to use share menu that uses Web Share API when possible, with a fallback to a nice share menu that tries to emulate the experience of the native one.

Features

• Incredibly simple to use. Just set one of the title, text, url, or image properties and call the share() method to make the magic happen;
• Highly customizable. It offers a great material design UI by default, but it is also designed to be as much customizable as possible through CSS custom properties and shadow parts. It also offers lots of built-in share targets and presets, with support for custom ones if needed;
• Compatible with any major browser. The Web Share API is still quite young, but the fallback dialog works on any browser supporting Custom Elements (directly or through a polyfill). Unlike the native share menu, the fallback will also work on desktop browsers and insecure contexts, so you will be able to offer a much more coherent experience to your users;
• Lightweight. The share-menu element itself weighs ~11.7 KB (~3.7 KB when compressed), while each built-in share target weighs on average ~700B (less than half the size when compressed);
• Thoroughly tested. Both the native and fallback behaviors are covered by tests, including each share target and preset. Minimum code coverage is set to 90% to ensure that each new feature maintains a high level of quality.

Installation

npm i share-menu
# or
yarn add share-menu

Without npm/yarn

If you just want to directly include the script without installing it as a dependency, use the unpkg CDN:

<!-- Main component -->
<script type="module" src="https://unpkg.com/[email protected]?module"></script>
<!-- Single share target -->
<script
  type="module"
  src="https://unpkg.com/[email protected]/targets/email.js?module"
></script>
<!-- Share target preset -->
<script
  type="module"
  src="https://unpkg.com/[email protected]/targets/presets/all.js?module"
></script>

Try it now!

Try copy-pasting this code on your browser's console in any website:

var a = document.createElement('script');
a.type = 'module';
a.textContent =
  'import"https://unpkg.com/[email protected]?module";import"https://unpkg.com/[email protected]/targets/presets/all.js?module";var b=document.createElement("share-menu"),c=document.createElement("share-target-preset-all");b.appendChild(c),document.body.appendChild(b),b.share();';
document.head.appendChild(a);

Note: these scripts will not work if the website implements a strict CSP (Content Security Policy). For example, these scripts won't work on GitHub.

Usage

Basic usage

<share-menu
  id="basicShareMenu"
  title="Ohai!"
  text="Just a test"
  url="https://www.example.com/"
  image="https://www.example.com/image.png"
>
  <share-target-preset-all></share-target-preset-all>
</share-menu>

<button onclick="basicShareMenu.share()">Share!</button>

With more configuration options and custom share targets

<share-menu
  id="customShareMenu"
  title="Awesome!"
  text="More customized share menu"
  url="https://www.example.com/"
  image="https://www.example.com/image.png"
  dialog-title="Share now"
  copy-hint="Copy to clipboard"
  handle="always"
  no-backdrop
>
  <share-target-email></share-target-email>
  <share-target-facebook></share-target-facebook>
  <share-target-telegram></share-target-telegram>
</share-menu>

<button onclick="customShareMenu.share()">Share!</button>

Defining the share targets (for the fallback dialog)

Built-in targets

This component comes with a large number of built-in targets that can be used to share content to the most popular social networks and messaging apps. These targets can be found in the targets folder and can be imported as follows:

import 'share-menu/targets/<target>.js';

Here you can see the list of the built-in targets, as well as the capabilities and limitations of each of them:

Target	Title	Text	URL	Image	Notes
Clipboard	✅	✅	✅	✅	Copying images is not supported on Firefox
Blogger	✅	✅	✅	❌
Diaspora	✅	❌	✅	❌
Douban	✅	✅	✅	❌
Email	✅	✅	✅	❌
Evernote	✅	❌	✅	❌
Facebook	✅	✅	✅	❌	URL only if not using Facebook JS SDK or not providing a Facebook App ID
Flipboard	✅	❌	✅	❌
Gmail	✅	✅	✅	❌
Google Translate	❌	❌	✅	❌	Translates the page at the given URL
Hacker News	✅	❌	✅	❌
Instapaper	✅	✅	✅	❌
KakaoTalk	❌	❌	✅	❌
LINE	❌	❌	✅	❌
LinkedIn	❌	❌	✅	❌
LiveJournal	✅	✅	✅	❌
Mastodon	✅	✅	✅	❌	Uses toot to ask for the instance on which to share the content
Messenger	❌	❌	✅	❌	Requires a Facebook App ID
Mix	❌	❌	✅	❌
Odnoklassniki (OK.ru)	✅	✅	✅	✅
Pinterest	✅	✅	✅	✅
Pocket	❌	❌	✅	❌
Print	❌	❌	✅	❌	Prints the page at the given URL
QZone	✅	✅	✅	❌
Reddit	✅	✅	✅	❌	Shares an URL if there is no text provided, otherwise a text with the URL appended at the end
Skype	✅	✅	✅	❌
SMS	✅	✅	✅	❌
Snapchat	❌	❌	✅	❌
Substack Notes	✅	✅	✅	❌
Telegram	✅	✅	✅	❌
Tumblr	✅	✅	✅	❌
Twitter	✅	✅	✅	❌
VKontakte (VK)	✅	✅	✅	❌
Weibo	✅	✅	✅	✅
WhatsApp	✅	✅	✅	❌
XING	❌	❌	✅	❌
Yahoo Mail	✅	✅	✅	❌

Presets

Given the large number of built-in targets, it can be quite tedious to add them all to the share menu. For this reason, this component offers a few presets that can be used to add a collection of targets at once. Presets can be found in the targets/presets folder and can be imported as follows:

import 'share-menu/targets/presets/<preset>.js';

Here is the list of the available presets, together with the targets included in each of them:

Preset	Targets included	Notes
All	All the built-in targets	Requires Facebook App ID for Messenger to be displayed
Top 15 Worldwide	Facebook, Messenger, WhatsApp, Weibo, Telegram, Snapchat, QZone, Pinterest, Twitter, Reddit, LinkedIn, Tumblr, Douban, VK, OK	Requires Facebook App ID for Messenger to be displayed

Custom share targets

Share targets in the fallback dialog are just simple HTML custom elements that implement the ShareTarget interface. More specifically, they must expose:

• A displayName field that contains the name of the target;
• A color field that contains the hex color of the target without the hash;
• An icon field that contains the SVG path of the icon of the target; Only the path must be provided (i.e. what you have inside the the d attribute of your SVG), not the whole SVG. Icon must will be rendered inside a 256x256 viewBox, so make sure that the icon fits correctly inside that area;
• A share method that takes the ShareMenu instance as parameter and that performs the actual share action when the target button is clicked;
• Optionally, an outline field that contains the hex color of the outline of the target without the hash;
• Optionally, a hint field that contains an additional hint text for the target.

See any of the built-in targets for a practical example on how to implement yours.

Styling

The following custom properties and shadow parts are available for styling:

Property	Description	Default
--sm-backdrop-color	The color of the backdrop	#000
--sm-background-color	The background color	#ece6f0
--sm-clipboard-background-color	The background color of the "copy to clipboard" section	#e6e0e9
--sm-title-color	The color of the title	#1c1b1f
--sm-ripple-color	The color of the ripple effect	#fff
--sm-labels-color	The color of the social labels	#1c1b1f
--sm-hint-color	The color of the hint labels	#49454e
--sm-handle-color	The color of the handle on top of the dialog	#79747e
--sm-divider-color	The color of the dividers	#c4c7c5
--sm-preview-color	The color of the preview of what is being shared	#49454e
dialog	The part assigned to the dialog	-
backdrop	The part assigned to the backdrop	-
title	The part assigned to the title	-
social-button	The part assigned to each social button	-
social-icon	The part assigned to each social icon	-
social-label	The part assigned to each social label	-

Note: for obvious reasons, these custom properties and shadow parts are not available when using the native share menu.

share-menu's Issues

whitelist share options

Hi

Is it possible to make a list of avaliable share options to be shown?

Conflict with polymerfire firebase messaging on-message event

I have the firebase-messaging element from polymerfire and the share-menu element in the same element in my app. When I receive a Firebase Cloud message on the foreground, the on-message event is fired. I think the widgets.js from Twitter also intercepts this event, resulting in this error:

Uncaught TypeError: Cannot read property 'twttr.button' of undefined at o (widgets.js:formatted:4740) at s._onMessage (widgets.js:formatted:4772) at widgets.js:formatted:694 at HTMLElement.fire (legacy-element-mixin.html:372) at firebase-messaging.html:114 at Array.forEach (<anonymous>) at Object.next (firebase-messaging.html:112) at firebase-app.js:3453 at firebase-app.js:3453 at <anonymous> o @ widgets.js:formatted:4740 _onMessage @ widgets.js:formatted:4772 (anonymous) @ widgets.js:formatted:694 fire @ legacy-element-mixin.html:372 (anonymous) @ firebase-messaging.html:114 (anonymous) @ firebase-messaging.html:112 (anonymous) @ firebase-app.js:3453 (anonymous) @ firebase-app.js:3453 Promise resolved (async) e.sendOne @ firebase-app.js:3453 e.forEachObserver @ firebase-app.js:3453 e.next @ firebase-app.js:3453 (anonymous) @ firebase-messaging.js:1618

Is there a way to fix this without changing the code in the bower_components folder?

Add an option to disable paper-dialog backdrop

Can you add an option to disable paper-dialog backdrop ?

Developer Usability

I am using this to share a users response from our game to a social media of their choice. However, I have come across a few issues hindering my progress.

For this, I only need to use a field that allows me to input text into it (like 'title' or 'text').

For Twitter, I do not need to share the 'URL' or 'via' properties; can they be hidden?

For Facebook, is it possible to have pre-filled text? Similarly to Twitter.

The numerous social media options are great! However, I will not need all of these, is it possible to have a selected number appear?

Uncaught ReferenceError: shareMenu is not defined

Hi,

I've imported this component into my project with

<link rel="import" href="../bower_components/share-menu/share-menu.html">

and use the demo code

<share-menu id="shareMenu" title="Ohai!" text="Just a test" url="https://www.example.com/"></share-menu> <button onclick="shareMenu.share()">Share!</button>

I get console error:
Uncaught ReferenceError: shareMenu is not defined
at HTMLElement.onclick

Feature Request: Grab title and text from metatags

Hi

I've now setup the element in my project, since I can't use within an element I was wondering if you can add a feature that will grab the title from the metatag title and grab the text from the metatag description.

I think this will be a good enhancement and make it easier to implement.

Thank you for your great work!

How to use with React?

I am trying to configure this with React and currently, I have the following:

import "share-menu/share-menu.js"

...

return (
	<share-menu
		id="shareMenu"
		title="Ohai!"
		text="Just a test"
		url="https://www.example.com/"
		socials={["telegram", "whatsapp","email", "clipboard", "sms", "twitter"]}
	/>
)

Although it does not register the "socials" since React turns it into a string. What's the best way to go about this?