browserux-share-button

v1.1.1

Published

a month ago

A smart, customizable Web Component for sharing content via Web Share API with graceful fallback.

EN | FR

BrowserUX Share Button

A modern solution to enable seamless content sharing across all devices and platforms.

BrowserUX Share Button is a lightweight, accessible, and customizable Web Component that simplifies sharing URLs via the native Web Share API, when available, or a responsive fallback modal. It supports multiple platforms (Email, X, WhatsApp, etc.), automatically retrieves share metadata, and offers full localization, visual customization, and framework compatibility.

Features

📱 Uses the native Web Share API when available (mobile, PWA)
🗂 Falls back to a rich modal with platform links on desktop
🔗 Copy-to-clipboard button with app icon, title, and URL preview
🌐 8 built-in platforms: Email, X, Facebook, WhatsApp, SMS, LinkedIn, Telegram, Reddit
🔌 Custom platform registry via ShareButton.registerPlatform()
🧠 Auto-resolves share data from document.title, <meta>, and Web App Manifest
🌍 Built-in i18n for 12 languages, auto-detected from <html lang>
♿ Accessible: keyboard navigation, focus trapping, focus restoration
📡 7 custom events: bux:share-success, bux:share-abort, bux:copy-success, and more
🖱 Programmatic API: share(), setShareData(), openFallback(), closeFallback()
🎨 Fully customizable via CSS custom properties
🧩 Optional Shadow DOM, disable with no-shadow

Installation

npm install browserux-share-button

Or via CDN:

<script type="module" src="https://unpkg.com/browserux-share-button/dist/browserux-share-button.esm.js"></script>

Usage

import 'browserux-share-button';

<browserux-share-button></browserux-share-button>

With explicit share data and platform control:

<browserux-share-button
  title="My article"
  text="A short description"
  url="https://example.com/article"
  lang="en"
  facebook="false"
  sms="false"
></browserux-share-button>

Parameters

| Parameter | Type | Description | |---|---|---| | url | Attribute | URL to share (default: location.href) | | title | Attribute | Share title (default: document.title) | | text | Attribute | Share description (default: <meta description>) | | lang | Attribute | Language code for built-in labels | | manifest-src | Attribute | Custom path to Web App Manifest | | no-shadow | Attribute | Disable Shadow DOM encapsulation | | [platform]="false" | Attribute | Disable a platform: email, x, facebook, whatsapp, sms, linkedin, telegram, reddit | | icon | Slot | Custom icon inside the share button (default: 🔗) | | bux:share-success | Event | Native share completed, e.detail: { title, text, url } | | bux:share-abort | Event | User cancelled the native share dialog | | bux:share-error | Event | Share failed, e.detail: { error } | | bux:fallback-open | Event | Fallback modal opened | | bux:fallback-close | Event | Fallback modal closed | | bux:copy-success | Event | Link copied, e.detail: { url } | | bux:copy-error | Event | Clipboard write failed, e.detail: { error } | | share() | Method | Trigger share programmatically | | setShareData(data) | Method | Update share data at runtime | | openFallback() | Method | Open the fallback modal programmatically | | closeFallback() | Method | Close the fallback modal programmatically |

Documentation

For detailed documentation, see docs/index.md.

Guide

Introduction : what it is, the two-path approach, metadata resolution
Getting started : installation via npm or CDN, basic usage
How it works : lifecycle, Web Share API, fallback modal, accessibility
Framework usage : React, Vue, Angular, vanilla JS
Customization : CSS custom properties for button and modal

Reference

Attributes : url, title, text, lang, no-shadow, platform disabling
Events : all bux:* events with payloads and use cases
Slots : icon slot for custom button icon
Programmatic API : share(), setShareData(), openFallback(), closeFallback()
Platforms : built-in platforms and custom platform registry
Utilities : getShareIcon, getBestIconUrl

Additional reference

Compatibility : browser support, framework compatibility, build formats
Contributing : report a bug, suggest an improvement, submit a PR

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme