diff --git a/.github/copilot/integrate-analytics.prompt.md b/.github/copilot/integrate-analytics.prompt.md
index 60cd595..cc8f4c6 100644
--- a/.github/copilot/integrate-analytics.prompt.md
+++ b/.github/copilot/integrate-analytics.prompt.md
@@ -41,14 +41,14 @@ forwards to whatever tool they choose.
## 2 — Core events catalogue
-| `eventName` | `interactionType` | Fires when |
-| ---------------------------- | ----------------- | ----------------------------------------------- |
-| `social_share_popup_open` | `popup_open` | Share modal/popup opens |
-| `social_share_popup_close` | `popup_close` | Modal closes (button, overlay, or Esc key) |
-| `social_share_click` | `share` | User clicks a platform button (share intent) |
-| `social_share_success` | `share` | Platform share window opened successfully |
-| `social_share_copy` | `copy` | User copies the link to clipboard |
-| `social_share_error` | `error` | Share or copy action failed |
+| `eventName` | `interactionType` | Fires when |
+| -------------------------- | ----------------- | -------------------------------------------- |
+| `social_share_popup_open` | `popup_open` | Share modal/popup opens |
+| `social_share_popup_close` | `popup_close` | Modal closes (button, overlay, or Esc key) |
+| `social_share_click` | `share` | User clicks a platform button (share intent) |
+| `social_share_success` | `share` | Platform share window opened successfully |
+| `social_share_copy` | `copy` | User copies the link to clipboard |
+| `social_share_error` | `error` | Share or copy action failed |
---
@@ -59,7 +59,7 @@ forwards to whatever tool they choose.
```js
// Fires on the container element and bubbles through the DOM (composed:true
// means it also crosses shadow-DOM boundaries).
-document.addEventListener("social-share", (e) => {
+document.addEventListener('social-share', (e) => {
const payload = e.detail;
// Forward to your analytics tool here
});
@@ -72,7 +72,7 @@ and Mixpanel both need the same event.
```js
new SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
onAnalytics: (payload) => {
// Forward to your analytics tool here
},
@@ -96,11 +96,8 @@ Load the adapters file **in addition to** the main library script:
const { GoogleAnalyticsAdapter, MixpanelAdapter } = window.SocialShareAnalytics;
new SocialShareButton({
- container: "#share-button",
- analyticsPlugins: [
- new GoogleAnalyticsAdapter(),
- new MixpanelAdapter(),
- ],
+ container: '#share-button',
+ analyticsPlugins: [new GoogleAnalyticsAdapter(), new MixpanelAdapter()],
});
```
@@ -125,7 +122,7 @@ Prerequisite: GA4 `gtag.js` snippet loaded by the host.
const { GoogleAnalyticsAdapter } = window.SocialShareAnalytics;
new SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
analyticsPlugins: [new GoogleAnalyticsAdapter()],
});
@@ -135,7 +132,7 @@ new SocialShareButton({
Custom event category (optional):
```js
-new GoogleAnalyticsAdapter({ eventCategory: "engagement" })
+new GoogleAnalyticsAdapter({ eventCategory: 'engagement' });
```
### Mixpanel
@@ -145,7 +142,7 @@ Prerequisite: `mixpanel-browser` snippet or SDK loaded.
```js
const { MixpanelAdapter } = window.SocialShareAnalytics;
new SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
analyticsPlugins: [new MixpanelAdapter()],
});
// Calls: mixpanel.track(eventName, { platform, url, ... })
@@ -156,7 +153,7 @@ new SocialShareButton({
```js
const { SegmentAdapter } = window.SocialShareAnalytics;
new SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
analyticsPlugins: [new SegmentAdapter()],
});
// Calls: analytics.track(eventName, { platform, url, ... })
@@ -169,7 +166,7 @@ Prerequisite: Plausible `script.js` loaded with custom events enabled.
```js
const { PlausibleAdapter } = window.SocialShareAnalytics;
new SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
analyticsPlugins: [new PlausibleAdapter()],
});
// Calls: plausible(eventName, { props: { platform, url, ... } })
@@ -180,7 +177,7 @@ new SocialShareButton({
```js
const { PostHogAdapter } = window.SocialShareAnalytics;
new SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
analyticsPlugins: [new PostHogAdapter()],
});
// Calls: posthog.capture(eventName, { platform, url, ... })
@@ -195,8 +192,8 @@ const { CustomAdapter } = window.SocialShareAnalytics;
new SocialShareButton({
analyticsPlugins: [
new CustomAdapter((payload) => {
- fetch("/api/analytics", {
- method: "POST",
+ fetch('/api/analytics', {
+ method: 'POST',
body: JSON.stringify(payload),
});
}),
@@ -231,17 +228,17 @@ GA4, Mixpanel, and a custom endpoint at the same time:
```js
const { GoogleAnalyticsAdapter, MixpanelAdapter, CustomAdapter } = window.SocialShareAnalytics;
-document.addEventListener("social-share", (e) => {
- console.log("Raw event:", e.detail); // Debugging / logging
+document.addEventListener('social-share', (e) => {
+ console.log('Raw event:', e.detail); // Debugging / logging
});
new SocialShareButton({
- container: "#share-button",
- componentId: "homepage-hero",
+ container: '#share-button',
+ componentId: 'homepage-hero',
analyticsPlugins: [
new GoogleAnalyticsAdapter(),
new MixpanelAdapter(),
- new CustomAdapter((p) => fetch("/log", { method: "POST", body: JSON.stringify(p) })),
+ new CustomAdapter((p) => fetch('/log', { method: 'POST', body: JSON.stringify(p) })),
],
});
```
@@ -255,7 +252,7 @@ development. Remove or set to `false` in production.
```js
new SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
debug: true,
// → [SocialShareButton Analytics] { version: '1.0', source: 'social-share-button', ... }
});
@@ -271,7 +268,7 @@ instrumentation must be explicitly consented to before activation.
```js
new SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
analytics: false,
});
```
diff --git a/.github/copilot/integrate-social-share-button.prompt.md b/.github/copilot/integrate-social-share-button.prompt.md
index 3b7a24b..ffd571d 100644
--- a/.github/copilot/integrate-social-share-button.prompt.md
+++ b/.github/copilot/integrate-social-share-button.prompt.md
@@ -25,11 +25,11 @@ You are helping a developer integrate the **SocialShareButton** library
The README defines **3 installation methods**. Ask (or infer) which the developer wants:
-| Method | When to use |
-|--------|-------------|
-| **Method 1 — CDN (Recommended)** | Most projects. No build step needed. Load via `
```
@@ -99,8 +102,8 @@ No framework. Just add the CDN tags directly:
**Step 2:** Open an **existing** component that renders on every page — typically `src/components/Header.jsx`, `src/layouts/MainLayout.jsx`, or your root `App.jsx`. Add the snippet below to that component so the share button is consistently available across your app.
```jsx
-import { useEffect, useRef } from "react";
-import { useLocation } from "react-router-dom"; // omit if not using React Router
+import { useEffect, useRef } from 'react';
+import { useLocation } from 'react-router-dom'; // omit if not using React Router
// ⬇️ Replace 'Header' with the name of the component where you want the
// share button to appear — e.g. Navbar, MainLayout, App, etc.
@@ -113,7 +116,7 @@ function Header() {
if (initRef.current || !window.SocialShareButton) return;
shareButtonRef.current = new window.SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
});
initRef.current = true;
@@ -150,13 +153,9 @@ function Header() {
**Step 1:** Add CDN to `app/layout.tsx`:
```tsx
-import Script from "next/script";
+import Script from 'next/script';
-export default function RootLayout({
- children,
-}: {
- children: React.ReactNode;
-}) {
+export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
@@ -180,10 +179,10 @@ export default function RootLayout({
**Step 2:** Because `SocialShareButton` manipulates the DOM, it must run inside a **Client Component** (note the `"use client"` directive at the top). Add the snippet below to an existing component such as `app/components/Header.tsx` or `app/components/Navbar.tsx` — any component already included in your layout.
```tsx
-"use client";
+'use client';
-import { useEffect, useRef } from "react";
-import { usePathname } from "next/navigation";
+import { useEffect, useRef } from 'react';
+import { usePathname } from 'next/navigation';
// ⬇️ Replace 'Header' with the name of the component where you want the
// share button to appear — e.g. Navbar, MainLayout, App, etc.
@@ -195,11 +194,10 @@ export default function Header() {
useEffect(() => {
const initButton = () => {
- if (initRef.current || !window.SocialShareButton || !containerRef.current)
- return;
+ if (initRef.current || !window.SocialShareButton || !containerRef.current) return;
shareButtonRef.current = new window.SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
});
initRef.current = true;
};
@@ -262,7 +260,7 @@ declare global {
**Step 1:** Add CDN to `pages/_document.tsx`:
```tsx
-import { Html, Head, Main, NextScript } from "next/document";
+import { Html, Head, Main, NextScript } from 'next/document';
export default function Document() {
return (
@@ -286,8 +284,8 @@ export default function Document() {
**Step 2:** Open an existing component that is rendered on every page — typically `components/Header.tsx`, `components/Navbar.tsx`, or `components/Layout.tsx`. Since `_document.tsx` loads the script globally, the button is ready to initialize in any of these components.
```tsx
-import { useEffect, useRef } from "react";
-import { useRouter } from "next/router";
+import { useEffect, useRef } from 'react';
+import { useRouter } from 'next/router';
// ⬇️ Replace 'Header' with the name of the component where you want the
// share button to appear — e.g. Navbar, MainLayout, App, etc.
@@ -299,11 +297,10 @@ export default function Header() {
useEffect(() => {
const initButton = () => {
- if (initRef.current || !window.SocialShareButton || !containerRef.current)
- return;
+ if (initRef.current || !window.SocialShareButton || !containerRef.current) return;
shareButtonRef.current = new window.SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
});
initRef.current = true;
};
@@ -384,7 +381,7 @@ declare global {
// Add to your component's template/HTML first,
// then initialize once the DOM is ready (e.g., in mounted(), ngAfterViewInit(), or useEffect()):
new window.SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
});
```
@@ -395,10 +392,10 @@ new window.SocialShareButton({
Use when the project has a bundler (Webpack, Vite, etc.) and the developer prefers `import` syntax. Works in any framework.
```javascript
-import SocialShareButton from "social-share-button-aossie";
-import "social-share-button-aossie/src/social-share-button.css";
+import SocialShareButton from 'social-share-button-aossie';
+import 'social-share-button-aossie/src/social-share-button.css';
-new SocialShareButton({ container: "#share-button" });
+new SocialShareButton({ container: '#share-button' });
```
> No CDN tags needed — the npm package includes both JS and CSS.
@@ -412,10 +409,10 @@ Only use this when the developer **explicitly** wants a reusable JSX component.
Tell them to copy `src/social-share-button-react.jsx` from the library into their project — **do not create a new file from scratch**.
```jsx
-import { SocialShareButton } from "./components/SocialShareButton";
+import { SocialShareButton } from './components/SocialShareButton';
function App() {
- return ;
+ return ;
}
```
@@ -423,30 +420,30 @@ function App() {
## All constructor options
-| Option | Type | Default | Description |
-| ------------------ | -------------- | ---------------------- | -------------------------------------------------- |
-| `container` | string/Element | — | **Required.** CSS selector or DOM element |
-| `url` | string | `window.location.href` | URL to share |
-| `title` | string | `document.title` | Share title/headline |
-| `description` | string | `''` | Additional description text |
-| `hashtags` | array | `[]` | e.g. `['js', 'webdev']` |
-| `via` | string | `''` | Twitter handle (without @) |
+| Option | Type | Default | Description |
+| ------------------ | -------------- | ---------------------- | ---------------------------------------------------------- |
+| `container` | string/Element | — | **Required.** CSS selector or DOM element |
+| `url` | string | `window.location.href` | URL to share |
+| `title` | string | `document.title` | Share title/headline |
+| `description` | string | `''` | Additional description text |
+| `hashtags` | array | `[]` | e.g. `['js', 'webdev']` |
+| `via` | string | `''` | Twitter handle (without @) |
| `platforms` | array | All platforms | `whatsapp facebook twitter linkedin telegram reddit email` |
-| `buttonText` | string | `'Share'` | Button label text |
-| `buttonStyle` | string | `'default'` | `default` `primary` `compact` `icon-only` |
-| `buttonColor` | string | `''` | Custom button background color |
-| `buttonHoverColor` | string | `''` | Custom button hover color |
-| `customClass` | string | `''` | Additional CSS class for button |
-| `theme` | string | `'dark'` | `dark` or `light` |
-| `modalPosition` | string | `'center'` | Modal position on screen |
-| `showButton` | boolean | `true` | Show/hide the share button |
-| `onShare` | function | `null` | `(platform, url) => void` |
-| `onCopy` | function | `null` | `(url) => void` |
-| `analytics` | boolean | `true` | Set `false` to disable all event emission |
-| `onAnalytics` | function | `null` | `(payload) => void` — direct analytics hook |
-| `analyticsPlugins` | array | `[]` | Adapter instances from `social-share-analytics.js` |
-| `componentId` | string | `null` | Label this instance for analytics tracking |
-| `debug` | boolean | `false` | Log analytics events to console |
+| `buttonText` | string | `'Share'` | Button label text |
+| `buttonStyle` | string | `'default'` | `default` `primary` `compact` `icon-only` |
+| `buttonColor` | string | `''` | Custom button background color |
+| `buttonHoverColor` | string | `''` | Custom button hover color |
+| `customClass` | string | `''` | Additional CSS class for button |
+| `theme` | string | `'dark'` | `dark` or `light` |
+| `modalPosition` | string | `'center'` | Modal position on screen |
+| `showButton` | boolean | `true` | Show/hide the share button |
+| `onShare` | function | `null` | `(platform, url) => void` |
+| `onCopy` | function | `null` | `(url) => void` |
+| `analytics` | boolean | `true` | Set `false` to disable all event emission |
+| `onAnalytics` | function | `null` | `(payload) => void` — direct analytics hook |
+| `analyticsPlugins` | array | `[]` | Adapter instances from `social-share-analytics.js` |
+| `componentId` | string | `null` | Label this instance for analytics tracking |
+| `debug` | boolean | `false` | Log analytics events to console |
---
@@ -469,7 +466,7 @@ const shareButton = useRef(null);
useEffect(() => {
shareButton.current = new window.SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
});
}, []);
@@ -487,25 +484,25 @@ useEffect(() => {
## Troubleshooting
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| Multiple buttons appearing | Component re-renders creating duplicate instances | Use `useRef` + `initRef` guard (shown in all examples above) |
-| Button not appearing | Script loads after component renders | Add `if (window.SocialShareButton)` null check |
-| Modal not opening | CSS not loaded or ID mismatch | Verify CSS CDN in ``; match `container: '#share-button'` with `
` |
-| `TypeError: SocialShareButton is not a constructor` | CDN script not loaded yet | Use interval polling (see Next.js examples above) |
-| URL not updating on navigation | Component initialized once, doesn't track routes | Use `updateOptions()` on route change |
+| Symptom | Cause | Fix |
+| --------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Multiple buttons appearing | Component re-renders creating duplicate instances | Use `useRef` + `initRef` guard (shown in all examples above) |
+| Button not appearing | Script loads after component renders | Add `if (window.SocialShareButton)` null check |
+| Modal not opening | CSS not loaded or ID mismatch | Verify CSS CDN in ``; match `container: '#share-button'` with `
` |
+| `TypeError: SocialShareButton is not a constructor` | CDN script not loaded yet | Use interval polling (see Next.js examples above) |
+| URL not updating on navigation | Component initialized once, doesn't track routes | Use `updateOptions()` on route change |
---
## Common mistakes to prevent
-| ❌ Wrong | ✅ Correct |
-|---------|-----------|
-| Creating `ShareButton.jsx` / `ShareButton.tsx` | Add directly to existing `Header.jsx`, `Navbar.tsx`, etc. |
-| Calling `new SocialShareButton()` inside JSX `return` | Call only inside `useEffect` / lifecycle hook |
-| Not calling `destroy()` on unmount | Always clean up — prevents duplicate modals on re-mount |
-| Mismatched container ID | `container: '#share-button'` must exactly match `
` |
-| Script loads after component renders in Next.js | Use `strategy="beforeInteractive"` **or** poll with `setInterval` |
+| ❌ Wrong | ✅ Correct |
+| ----------------------------------------------------- | ------------------------------------------------------------------------- |
+| Creating `ShareButton.jsx` / `ShareButton.tsx` | Add directly to existing `Header.jsx`, `Navbar.tsx`, etc. |
+| Calling `new SocialShareButton()` inside JSX `return` | Call only inside `useEffect` / lifecycle hook |
+| Not calling `destroy()` on unmount | Always clean up — prevents duplicate modals on re-mount |
+| Mismatched container ID | `container: '#share-button'` must exactly match `
` |
+| Script loads after component renders in Next.js | Use `strategy="beforeInteractive"` **or** poll with `setInterval` |
---
@@ -516,4 +513,3 @@ useEffect(() => {
- Always modify **existing** files — never suggest creating new component files.
- When modifying an existing file, mark additions with `// ADD THIS`.
- Do not add abstractions, wrappers, or extra files beyond what the README shows.
-
diff --git a/README.md b/README.md
index bf8c605..55e0b54 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,6 @@
-
> ⚠️ **IMPORTANT**
>
> All project discussions happens on **[Discord](https://discord.com/channels/1022871757289422898/1479012884209078365)**.
@@ -75,6 +74,7 @@ Lightweight social sharing component for web applications. Zero dependencies, fr
- 🎯 Zero dependencies - pure vanilla JavaScript
- ⚛️ Framework support: React, Next.js, Vue, Angular, or plain HTML
- 🔄 Auto-detects current URL and page title
+- 🧠 Intelligent content detection — automatically extracts title & description from page metadata and semantic HTML
- 📱 Fully responsive and mobile-ready
- 🎨 Customizable themes (dark/light)
- ⚡ Lightweight (< 10KB gzipped)
@@ -86,7 +86,10 @@ Lightweight social sharing component for web applications. Zero dependencies, fr
### Via CDN (Recommended)
```html
-
+
```
@@ -101,11 +104,11 @@ Lightweight social sharing component for web applications. Zero dependencies, fr
No matter which framework you use, integration always follows the same 3 steps:
-| Step | What to do | Where |
-|------|-----------|-------|
-| **1️⃣ Load Library** | Add CSS + JS (CDN links) | Global layout file — `index.html` / `layout.tsx` / `_document.tsx` |
-| **2️⃣ Add Container** | Place `` | The UI component where you want the button to appear |
-| **3️⃣ Initialize** | Call `new SocialShareButton({ container: "#share-button" })` | Inside that component, after the DOM is ready (e.g. `useEffect`, `mounted`, `ngAfterViewInit`) |
+| Step | What to do | Where |
+| -------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
+| **1️⃣ Load Library** | Add CSS + JS (CDN links) | Global layout file — `index.html` / `layout.tsx` / `_document.tsx` |
+| **2️⃣ Add Container** | Place `` | The UI component where you want the button to appear |
+| **3️⃣ Initialize** | Call `new SocialShareButton({ container: "#share-button" })` | Inside that component, after the DOM is ready (e.g. `useEffect`, `mounted`, `ngAfterViewInit`) |
> 💡 Pick your framework below for the full copy-paste snippet:
@@ -132,8 +135,8 @@ No matter which framework you use, integration always follows the same 3 steps:
Open an **existing** component that renders on every page — typically `src/components/Header.jsx`, `src/layouts/MainLayout.jsx`, or your root `App.jsx`. Add the snippet below to that component so the share button is consistently available across your app.
```jsx
-import { useEffect, useRef } from "react";
-import { useLocation } from "react-router-dom"; // omit if not using React Router
+import { useEffect, useRef } from 'react';
+import { useLocation } from 'react-router-dom'; // omit if not using React Router
// ⬇️ Replace 'Header' with the name of the component where you want the
// share button to appear — e.g. Navbar, MainLayout, App, etc.
@@ -146,7 +149,7 @@ function Header() {
if (initRef.current || !window.SocialShareButton) return;
shareButtonRef.current = new window.SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
});
initRef.current = true;
@@ -184,13 +187,9 @@ function Header() {
### Step 1: Add CDN to `app/layout.tsx`
```tsx
-import Script from "next/script";
+import Script from 'next/script';
-export default function RootLayout({
- children,
-}: {
- children: React.ReactNode;
-}) {
+export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
@@ -216,10 +215,10 @@ export default function RootLayout({
Because `SocialShareButton` manipulates the DOM, it must run inside a **Client Component** (note the `"use client"` directive at the top). Add the snippet below to an existing component such as `app/components/Header.tsx` or `app/components/Navbar.tsx` — any component already included in your layout.
```tsx
-"use client";
+'use client';
-import { useEffect, useRef } from "react";
-import { usePathname } from "next/navigation";
+import { useEffect, useRef } from 'react';
+import { usePathname } from 'next/navigation';
// ⬇️ Replace 'Header' with the name of the component where you want the
// share button to appear — e.g. Navbar, MainLayout, App, etc.
@@ -231,11 +230,10 @@ export default function Header() {
useEffect(() => {
const initButton = () => {
- if (initRef.current || !window.SocialShareButton || !containerRef.current)
- return;
+ if (initRef.current || !window.SocialShareButton || !containerRef.current) return;
shareButtonRef.current = new window.SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
});
initRef.current = true;
};
@@ -299,7 +297,7 @@ declare global {
### Step 1: Add CDN to `pages/_document.tsx`
```tsx
-import { Html, Head, Main, NextScript } from "next/document";
+import { Html, Head, Main, NextScript } from 'next/document';
export default function Document() {
return (
@@ -325,8 +323,8 @@ export default function Document() {
Open an existing component that is rendered on every page — typically `components/Header.tsx`, `components/Navbar.tsx`, or `components/Layout.tsx`. Since `_document.tsx` loads the script globally, the button is ready to initialize in any of these components.
```tsx
-import { useEffect, useRef } from "react";
-import { useRouter } from "next/router";
+import { useEffect, useRef } from 'react';
+import { useRouter } from 'next/router';
// ⬇️ Replace 'Header' with the name of the component where you want the
// share button to appear — e.g. Navbar, MainLayout, App, etc.
@@ -338,11 +336,10 @@ export default function Header() {
useEffect(() => {
const initButton = () => {
- if (initRef.current || !window.SocialShareButton || !containerRef.current)
- return;
+ if (initRef.current || !window.SocialShareButton || !containerRef.current) return;
shareButtonRef.current = new window.SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
});
initRef.current = true;
};
@@ -426,7 +423,7 @@ Open your root or layout component (e.g., `App.vue`, `app.component.html`, or `A
// Add to your component's template/HTML first,
// then initialize once the DOM is ready (e.g., in mounted(), ngAfterViewInit(), or useEffect()):
new window.SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
});
```
@@ -434,43 +431,124 @@ new window.SocialShareButton({
---
+## Automatic Content Detection
+
+SocialShareButton can automatically detect the title and description for sharing from your page — no manual configuration needed.
+
+### How It Works
+
+When `title` or `description` props are not provided, the component runs a lightweight detection pass over the page:
+
+| Priority | Signal | Used for |
+| -------- | -------------------------------------------------------- | ---------------------- |
+| 1 | `` | Title |
+| 2 | `` | Title |
+| 3 | First `
` in `` / `` / `[role="main"]` | Title |
+| 4 | Common CMS selectors (`.post-title`, `.entry-title`, …) | Title |
+| 5 | `document.title` (strips common site name suffixes) | Title (fallback) |
+| 1 | `` | Description |
+| 2 | `` | Description |
+| 3 | `` | Description |
+| 4 | Main content body excerpt (150–200 chars) | Description (fallback) |
+
+No external libraries are loaded. The detector is inlined directly in the script — zero added bytes to `node_modules` and no network requests.
+
+### Zero-Config Usage
+
+```html
+
+
+
+```
+
+Or in React:
+
+```jsx
+// No title or description props needed — auto-detected from the page
+
+```
+
+### Manual Props Always Win
+
+If you supply `title` or `description`, auto-detection is bypassed for those fields. You can mix-and-match:
+
+```jsx
+new SocialShareButton({
+ container: '#share-button',
+ title: 'My Custom Title', // explicit — used as-is
+ // description omitted — auto-detected from page meta/body
+});
+```
+
+### Disabling Auto-Detection
+
+```jsx
+new SocialShareButton({
+ container: '#share-button',
+ autoDetect: false, // skip detection entirely
+ title: 'My Title',
+ description: 'My description',
+});
+```
+
+### SPA / Client-Side Navigation
+
+When the route changes, call `clearContentCache()` before updating options. The component will automatically re-detect content when `autoDetect` is enabled (default):
+
+```jsx
+// React Router / Next.js
+useEffect(() => {
+ SocialShareButton.clearContentCache();
+ shareButtonRef.current?.updateOptions({
+ url: window.location.href,
+ });
+}, [pathname]);
+```
+
+Note: You only need to provide `url` — if `autoDetect` is enabled (default), the component will automatically re-detect `title` and `description` from the new page's metadata. If you explicitly provide `title` or `description` in `updateOptions`, those values will be used instead of auto-detection.
+
+---
+
## Configuration
### Basic Options
```jsx
new SocialShareButton({
- container: "#share-button", // Required: CSS selector or DOM element
- url: "https://example.com", // Optional: defaults to window.location.href
- title: "Custom Title", // Optional: defaults to document.title
- buttonText: "Share", // Optional: button label text
- buttonStyle: "primary", // default | primary | compact | icon-only
- theme: "dark", // dark | light
- platforms: ["twitter", "linkedin"], // Optional: defaults to all platforms
+ container: '#share-button', // Required: CSS selector or DOM element
+ url: 'https://example.com', // Optional: defaults to window.location.href
+ title: 'Custom Title', // Optional: auto-detected from page metadata when omitted
+ buttonText: 'Share', // Optional: button label text
+ buttonStyle: 'primary', // default | primary | compact | icon-only
+ theme: 'dark', // dark | light
+ platforms: ['twitter', 'linkedin'], // Optional: defaults to all platforms
});
```
### All Available Options
-| Option | Type | Default | Description |
-| ------------------ | -------------- | ---------------------- | -------------------------------------------------- |
-| `container` | string/Element | - | **Required.** CSS selector or DOM element |
-| `url` | string | `window.location.href` | URL to share |
-| `title` | string | `document.title` | Share title/headline |
-| `description` | string | `''` | Additional description text |
-| `hashtags` | array | `[]` | Hashtags for posts (e.g., `['js', 'webdev']`) |
-| `via` | string | `''` | Twitter handle (without @) |
-| `platforms` | array | All platforms | Platforms to show (see below) |
-| `buttonText` | string | `'Share'` | Button label text |
-| `buttonStyle` | string | `'default'` | `default`, `primary`, `compact`, `icon-only` |
-| `buttonColor` | string | `''` | Custom button background color |
-| `buttonHoverColor` | string | `''` | Custom button hover color |
-| `customClass` | string | `''` | Additional CSS class for button |
-| `theme` | string | `'dark'` | `dark` or `light` |
-| `modalPosition` | string | `'center'` | Modal position on screen |
-| `showButton` | boolean | `true` | Show/hide the share button |
-| `onShare` | function | `null` | Callback when user shares: `(platform, url) => {}` |
-| `onCopy` | function | `null` | Callback when user copies link: `(url) => {}` |
+| Option | Type | Default | Description |
+| ------------------ | -------------- | ----------------------------------------------------------- | -------------------------------------------------------------------- |
+| `container` | string/Element | - | **Required.** CSS selector or DOM element |
+| `url` | string | `window.location.href` | URL to share |
+| `title` | string | auto-detected (og:title → h1 → document.title) | Share title/headline — auto-detected from page metadata when omitted |
+| `description` | string | auto-detected (og:description → meta description → excerpt) | Additional description text — auto-detected when omitted |
+| `hashtags` | array | `[]` | Hashtags for posts (e.g., `['js', 'webdev']`) |
+| `via` | string | `''` | Twitter handle (without @) |
+| `platforms` | array | All platforms | Platforms to show (see below) |
+| `buttonText` | string | `'Share'` | Button label text |
+| `buttonStyle` | string | `'default'` | `default`, `primary`, `compact`, `icon-only` |
+| `buttonColor` | string | `''` | Custom button background color |
+| `buttonHoverColor` | string | `''` | Custom button hover color |
+| `customClass` | string | `''` | Additional CSS class for button |
+| `theme` | string | `'dark'` | `dark` or `light` |
+| `modalPosition` | string | `'center'` | Modal position on screen |
+| `showButton` | boolean | `true` | Show/hide the share button |
+| `onShare` | function | `null` | Callback when user shares: `(platform, url) => {}` |
+| `onCopy` | function | `null` | Callback when user copies link: `(url) => {}` |
+| `autoDetect` | boolean | `true` | Auto-detect title/description from page when omitted |
**Available Platforms:**
`whatsapp`, `facebook`, `twitter`, `linkedin`, `telegram`, `reddit`, `email`
@@ -481,12 +559,12 @@ Control the text that appears when users share to social platforms:
```jsx
new SocialShareButton({
- container: "#share-button",
- url: "https://myproject.com",
- title: "Check out my awesome project!", // Main title/headline
- description: "An amazing tool for developers", // Additional description
- hashtags: ["javascript", "webdev", "opensource"], // Hashtags included in posts
- via: "MyProjectHandle", // Your Twitter handle
+ container: '#share-button',
+ url: 'https://myproject.com',
+ title: 'Check out my awesome project!', // Main title/headline
+ description: 'An amazing tool for developers', // Additional description
+ hashtags: ['javascript', 'webdev', 'opensource'], // Hashtags included in posts
+ via: 'MyProjectHandle', // Your Twitter handle
});
```
@@ -506,8 +584,8 @@ new SocialShareButton({
```jsx
new SocialShareButton({
- container: "#share-button",
- buttonStyle: "primary", // or 'default', 'compact', 'icon-only'
+ container: '#share-button',
+ buttonStyle: 'primary', // or 'default', 'compact', 'icon-only'
});
```
@@ -517,9 +595,9 @@ Pass `buttonColor` and `buttonHoverColor` to match your project's color scheme:
```jsx
new SocialShareButton({
- container: "#share-button",
- buttonColor: "#ff6b6b", // Button background color
- buttonHoverColor: "#ff5252", // Hover state color
+ container: '#share-button',
+ buttonColor: '#ff6b6b', // Button background color
+ buttonHoverColor: '#ff5252', // Hover state color
});
```
@@ -529,9 +607,9 @@ For more complex styling, use a custom CSS class:
```jsx
new SocialShareButton({
- container: "#share-button",
- buttonStyle: "primary",
- customClass: "my-custom-button",
+ container: '#share-button',
+ buttonStyle: 'primary',
+ customClass: 'my-custom-button',
});
```
@@ -555,23 +633,23 @@ Then in your CSS file:
```jsx
// Material Design Red
new SocialShareButton({
- container: "#share-button",
- buttonColor: "#f44336",
- buttonHoverColor: "#da190b",
+ container: '#share-button',
+ buttonColor: '#f44336',
+ buttonHoverColor: '#da190b',
});
// Tailwind Blue
new SocialShareButton({
- container: "#share-button",
- buttonColor: "#3b82f6",
- buttonHoverColor: "#2563eb",
+ container: '#share-button',
+ buttonColor: '#3b82f6',
+ buttonHoverColor: '#2563eb',
});
// Custom Brand Color
new SocialShareButton({
- container: "#share-button",
- buttonColor: "#your-brand-color",
- buttonHoverColor: "#your-brand-color-dark",
+ container: '#share-button',
+ buttonColor: '#your-brand-color',
+ buttonHoverColor: '#your-brand-color-dark',
});
```
@@ -588,12 +666,12 @@ new SocialShareButton({
```jsx
new SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
onShare: (platform, url) => {
console.log(`Shared on ${platform}: ${url}`);
},
onCopy: (url) => {
- console.log("Link copied:", url);
+ console.log('Link copied:', url);
},
});
```
@@ -605,11 +683,11 @@ new SocialShareButton({
### Using npm Package
```javascript
-import SocialShareButton from "social-share-button-aossie";
-import "social-share-button-aossie/src/social-share-button.css";
+import SocialShareButton from 'social-share-button-aossie';
+import 'social-share-button-aossie/src/social-share-button.css';
new SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
});
```
@@ -618,13 +696,22 @@ new SocialShareButton({
If you want a reusable React component, copy `src/social-share-button-react.jsx` to your project:
```jsx
-import { SocialShareButton } from "./components/SocialShareButton";
+import { SocialShareButton } from './components/SocialShareButton';
function App() {
- return ;
+ return ;
}
```
+> **Performance tip:** Array and callback props (`hashtags`, `platforms`, `analyticsPlugins`, `onShare`, `onCopy`, `onAnalytics`) are compared by reference. Passing inline literals (e.g. `platforms={['twitter']}`) creates a new reference on every parent render and triggers `updateOptions()` unnecessarily. Wrap them with `useMemo` / `useCallback` in your parent component:
+>
+> ```jsx
+> const platforms = useMemo(() => ['twitter', 'linkedin'], []);
+> const onShare = useCallback((platform, url) => console.log(platform, url), []);
+>
+> return ;
+> ```
+
### Update URL Dynamically (SPA)
```jsx
@@ -640,7 +727,7 @@ const shareButton = useRef(null);
useEffect(() => {
shareButton.current = new window.SocialShareButton({
- container: "#share-button",
+ container: '#share-button',
});
}, []);
@@ -676,7 +763,7 @@ useEffect(() => {
```jsx
if (window.SocialShareButton) {
- new window.SocialShareButton({ container: "#share-button" });
+ new window.SocialShareButton({ container: '#share-button' });
}
```
@@ -729,14 +816,14 @@ if (window.SocialShareButton) {
```jsx
// Professional networks only
new SocialShareButton({
- container: "#share-button",
- platforms: ["linkedin", "twitter", "email"],
+ container: '#share-button',
+ platforms: ['linkedin', 'twitter', 'email'],
});
// Messaging apps only
new SocialShareButton({
- container: "#share-button",
- platforms: ["whatsapp", "telegram"],
+ container: '#share-button',
+ platforms: ['whatsapp', 'telegram'],
});
```
@@ -744,9 +831,9 @@ new SocialShareButton({
```jsx
new SocialShareButton({
- container: "#share-button",
- buttonStyle: "icon-only",
- theme: "light",
+ container: '#share-button',
+ buttonStyle: 'icon-only',
+ theme: 'light',
});
```
diff --git a/docs/client-guide.md b/docs/client-guide.md
index 6b49350..da7d57d 100644
--- a/docs/client-guide.md
+++ b/docs/client-guide.md
@@ -8,12 +8,12 @@
Your audience is already sharing. Give them a button worth clicking.
-| What you get | What you skip |
-|---|---|
-| One-line install | Backend servers |
+| What you get | What you skip |
+| ---------------------- | --------------------------- |
+| One-line install | Backend servers |
| Works on any framework | Tracking or data collection |
-| Fully customizable | Lock-in or licensing fees |
-| Lightweight & fast | Build step (CDN option) |
+| Fully customizable | Lock-in or licensing fees |
+| Lightweight & fast | Build step (CDN option) |
---
diff --git a/eslint.config.js b/eslint.config.js
index 701e191..9b85c82 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -1,13 +1,13 @@
-import js from "@eslint/js";
-import globals from "globals";
+import js from '@eslint/js';
+import globals from 'globals';
export default [
js.configs.recommended,
{
- files: ["src/**/*.{js,jsx}"],
+ files: ['src/**/*.{js,jsx}'],
languageOptions: {
- ecmaVersion: "latest",
- sourceType: "module",
+ ecmaVersion: 'latest',
+ sourceType: 'module',
parserOptions: {
ecmaFeatures: {
jsx: true,
@@ -20,15 +20,15 @@ export default [
},
},
rules: {
- "no-console": "error",
- "no-unused-vars": ["warn", { "caughtErrorsIgnorePattern": "^_" }],
- "semi": ["error", "always"],
+ 'no-console': 'error',
+ 'no-unused-vars': ['warn', { caughtErrorsIgnorePattern: '^_' }],
+ semi: ['error', 'always'],
},
},
{
- files: ["eslint.config.js", "**/*.config.js"],
+ files: ['eslint.config.js', '**/*.config.js'],
languageOptions: {
- sourceType: "module",
+ sourceType: 'module',
globals: {
...globals.node,
},
diff --git a/index.html b/index.html
index 90db0da..f75efb6 100644
--- a/index.html
+++ b/index.html
@@ -391,6 +391,43 @@
Messaging
+
+
+
🤖 Content Auto-Detection
+
Automatically detects page title and extracts descriptions from meta tags or page content. Zero config required!
+
+
+
+
+
+<!-- Include via CDN -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/AOSSIE-Org/SocialShareButton@feature/socialshare-autodetect/src/social-share-button.css">
+<script src="https://cdn.jsdelivr.net/gh/AOSSIE-Org/SocialShareButton@feature/socialshare-autodetect/src/social-share-button.js"></script>
+
+<div id="demo-autodetect"></div>
+
+<script>
+ // Initialize with zero config for auto-detection
+ new SocialShareButton({
+ container: '#demo-autodetect'
+ });
+</script>
+