share-wc

Social share component with native Web Share API and platform fallbacks

Overview

<share-wc> provides social sharing with three-tier progressive enhancement:

  1. Tier 1 (native) — On supported platforms, a single button triggers the OS share sheet via navigator.share()
  2. Tier 2 (platforms) — On desktop, individual platform buttons open share URLs
  3. Tier 3 (no JS) — Slotted <a> links work without JavaScript
<share-wc></share-wc>

Attributes

Attribute Type Default Description
url string location.href URL to share
title string document.title Share title
text string Meta description Share description text
platforms string x,linkedin,bluesky,mastodon,whatsapp,email,copy Comma-separated platform list
variant string icon-label Visual variant: icon, label, icon-label
size string m Button size: s, m, l
label string Share Label for Tier 1 native button
color boolean absent Use platform brand colours
mastodon-instance string mastodon.social Mastodon instance for share URL
tier string auto Force tier: native or platforms. Overrides auto-detection.

Platforms

Choose which platforms to show with platforms. Order controls render order.

<share-wc platforms="x,linkedin,bluesky,email,copy"></share-wc>

Available Platforms

ID Label Action
xXOpens X/Twitter compose
twitterXAlias for x
facebookFacebookOpens Facebook sharer
linkedinLinkedInOpens LinkedIn share
whatsappWhatsAppOpens WhatsApp (native app on mobile)
telegramTelegramOpens Telegram share
blueskyBlueskyOpens Bluesky compose
mastodonMastodonOpens Mastodon share (configurable instance)
emailEmailOpens email client via mailto:
copyCopy linkCopies URL to clipboard with 2s feedback

Variants

Icon only

Show icons without labels using variant="icon".

<share-wc platforms="x,linkedin,bluesky,copy" variant="icon"></share-wc>

Label only

Show labels without icons using variant="label".

<share-wc platforms="x,linkedin,email,copy" variant="label"></share-wc>

Brand colours

Add color to apply platform brand colours.

<share-wc platforms="x,linkedin,whatsapp,bluesky,mastodon" color></share-wc>

Sizes

Use size="s" or size="l" for small or large buttons.

<share-wc platforms="x,linkedin,copy" size="s"></share-wc> <share-wc platforms="x,linkedin,copy"></share-wc> <share-wc platforms="x,linkedin,copy" size="l"></share-wc>

Explicit Share Data

Override the auto-detected URL, title, and text with explicit attributes.

<share-wc url="https://example.com/article" title="Interesting Article" text="A fascinating read about web components" platforms="x,linkedin,email,copy"> </share-wc>

Meta Resolution Order

FieldPriority
URLurl → <link rel="canonical"> → location.href
Titletitle → og:title → document.title
Texttext → meta[name=description] → og:description → empty

Progressive Enhancement

For full no-JS support, slot <a> elements with data-platform attributes. The component enhances them with click handlers and substitutes {url}, {title}, {text} tokens in href values.

<share-wc> <a href="https://x.com/intent/post?url={url}&text={title}" data-platform="x" target="_blank" rel="noopener noreferrer"> Post on X </a> <a href="https://www.linkedin.com/sharing/share-offsite/?url={url}" data-platform="linkedin" target="_blank" rel="noopener noreferrer"> LinkedIn </a> <button type="button" data-platform="copy">Copy link</button> </share-wc>

Force platform buttons

On devices with navigator.share (macOS, iOS, Android), the component auto-selects the native share sheet. Use tier="platforms" to always show individual platform buttons instead, giving authors full control over which platforms appear.

<!-- Force platform buttons even on devices with Web Share API --> <share-wc tier="platforms" platforms="x,linkedin,bluesky,copy" color></share-wc>

Native-only mode

Use platforms="native-only" to show only the native share button. Hides entirely on platforms without Web Share API support.

<share-wc platforms="native-only"></share-wc>

Mastodon Instance

Set a custom Mastodon instance with mastodon-instance. Defaults to mastodon.social.

<share-wc platforms="mastodon" mastodon-instance="fosstodon.org"> </share-wc>

Events

Event Detail Description
share-wc:open { platform } Fired when a share is initiated
share-wc:success { platform } Fired after successful share or copy
share-wc:error { platform, error } Fired on failure (user cancel is not an error)
const share = document.querySelector('share-wc'); share.addEventListener('share-wc:success', (e) => { console.log(`Shared via ${e.detail.platform}`); }); share.addEventListener('share-wc:error', (e) => { console.error(`Share failed: ${e.detail.error}`); });

JavaScript API

Property/Method Type Description
url get/set Current share URL
title get/set Current share title
text get/set Current share description
share() method Programmatically trigger native share
const share = document.querySelector('share-wc'); // Update share data share.url = 'https://example.com/new-page'; share.title = 'New Title'; // Trigger native share programmatically share.share();

Accessibility

  • Tier 1 button has aria-label="Share this page"
  • Tier 2 wraps buttons in <nav aria-label="Share this page">
  • Each platform button has an accessible label: "Share on X", "Copy link", etc.
  • Copy button announces "Copied!" via aria-live="polite"
  • Icons are hidden from assistive technology with aria-hidden="true"
  • Labels remain in the DOM for icon variant (visually hidden, not removed)
  • Reduced motion: transitions disabled via prefers-reduced-motion