From dfbebb965501151826ece44c3f21dcd890e38dca Mon Sep 17 00:00:00 2001 From: Eden Gilbert Date: Tue, 24 Feb 2026 20:57:00 +0300 Subject: [PATCH] docs: add Astro framework support to Quick Start Guide --- README.md | 288 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 181 insertions(+), 107 deletions(-) diff --git a/README.md b/README.md index 8345a7b..a765765 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # +
@@ -53,16 +54,16 @@ Lightweight social sharing component for web applications. Zero dependencies, framework-agnostic. - [![npm version](https://img.shields.io/npm/v/social-share-button-aossie.svg)](https://www.npmjs.com/package/social-share-button-aossie) [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE) --- + ## Features - 🌐 Multiple platforms: WhatsApp, Facebook, X, LinkedIn, Telegram, Reddit, Email - 🎯 Zero dependencies - pure vanilla JavaScript -- ⚛️ Framework support: React, Next.js, Vue, Angular, or plain HTML +- ⚛️ Framework support: React, Next.js, Vue, Angular, Astro, or plain HTML - 🔄 Auto-detects current URL and page title - 📱 Fully responsive and mobile-ready - 🎨 Customizable themes (dark/light) @@ -75,7 +76,10 @@ Lightweight social sharing component for web applications. Zero dependencies, fr ### Via CDN (Recommended) ```html - + ``` @@ -93,7 +97,10 @@ Lightweight social sharing component for web applications. Zero dependencies, fr ```html - +
@@ -104,17 +111,18 @@ Lightweight social sharing component for web applications. Zero dependencies, fr ### Step 2: In your **existing** React component (e.g., `MainLayout.jsx`, `Header.jsx`, or wherever you want the button): ```jsx -import { useEffect, useRef } from 'react'; +import { useEffect, useRef } from "react"; -function YourComponent() { // Use your actual component name (Header, Navbar, etc.) +function YourComponent() { + // Use your actual component name (Header, Navbar, etc.) const shareButtonRef = useRef(null); const initRef = useRef(false); useEffect(() => { if (initRef.current || !window.SocialShareButton) return; - + shareButtonRef.current = new window.SocialShareButton({ - container: '#share-button' + container: "#share-button", }); initRef.current = true; @@ -142,20 +150,24 @@ function YourComponent() { // Use your actual component name (Header, Navbar, e ### 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 ( - {children} - + + +``` + +> **Note:** The `is:inline` directive tells Astro to leave the script tag as-is in the HTML output instead of bundling it, which is required for CDN scripts. + +### Step 2: In your **existing** Astro page or component (e.g., `src/pages/index.astro`): + +```astro +--- +import Layout from '../layouts/Layout.astro'; +--- + +
+
+
+ + + +``` + +> **Tip:** Astro pages are server-rendered as static HTML by default, so the CDN-loaded script works seamlessly without any framework adapters. + + + --- ## Configuration @@ -353,37 +424,37 @@ new window.SocialShareButton({ ```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: 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 }); ``` ### 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 | `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) => {}` | **Available Platforms:** `whatsapp`, `facebook`, `twitter`, `linkedin`, `telegram`, `reddit`, `email` @@ -394,16 +465,17 @@ 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 }); ``` **How messages are customized per platform:** + - **WhatsApp:** `title` + `description` + `hashtags` + link - **Facebook:** `title` + `description` + `hashtags` + link - **Twitter/X:** `title` + `description` + `hashtags` + `via` handle + link @@ -418,8 +490,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' }); ``` @@ -429,9 +501,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 }); ``` @@ -441,9 +513,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", }); ``` @@ -467,46 +539,46 @@ 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", }); ``` ### Button Styles -| Style | Description | -|-------|-------------| -| `default` | Standard button with icon and text | -| `primary` | Gradient button (recommended) | -| `compact` | Smaller size for tight spaces | -| `icon-only` | Icon without text | +| Style | Description | +| ----------- | ---------------------------------- | +| `default` | Standard button with icon and text | +| `primary` | Gradient button (recommended) | +| `compact` | Smaller size for tight spaces | +| `icon-only` | Icon without text | ### Callbacks ```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); + }, }); ``` @@ -517,11 +589,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", }); ``` @@ -530,10 +602,10 @@ 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 ; } ``` @@ -543,15 +615,15 @@ function App() { const shareButton = useRef(null); useEffect(() => { - shareButton.current = new window.SocialShareButton({ - container: '#share-button' + shareButton.current = new window.SocialShareButton({ + container: "#share-button", }); }, []); useEffect(() => { if (shareButton.current) { - shareButton.current.updateOptions({ - url: window.location.href + shareButton.current.updateOptions({ + url: window.location.href, }); } }, [pathname]); // Update on route change @@ -576,9 +648,10 @@ useEffect(() => { **Cause:** Script loads after component renders **Solution:** Add null check: + ```jsx if (window.SocialShareButton) { - new window.SocialShareButton({ container: '#share-button' }); + new window.SocialShareButton({ container: "#share-button" }); } ``` @@ -589,7 +662,8 @@ if (window.SocialShareButton) { **Cause:** CSS not loaded or ID mismatch -**Solution:** +**Solution:** + - Verify CSS CDN link in `` - Match container ID: `container: '#share-button'` = `
` @@ -630,14 +704,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"], }); ``` @@ -645,9 +719,9 @@ new SocialShareButton({ ```jsx new SocialShareButton({ - container: '#share-button', - buttonStyle: 'icon-only', - theme: 'light' + container: "#share-button", + buttonStyle: "icon-only", + theme: "light", }); ```