@sonardigital/social-share

Lightweight React utilities to add social sharing buttons and Open Graph/Twitter meta tags to your app. Includes a provider/context, share hooks for popular platforms, and a tiny Open Graph helper.

Install

npm install @sonardigital/social-share
# or
yarn add @sonardigital/social-share
# or
pnpm add @sonardigital/social-share

Peer deps: react.

What you get

• Provider: SocialShareWrapper to expose share methods via React context
• Hooks:
  • useSocialShare() returns share methods without context
  • useSocialShareContext() reads the methods from context
  • useOpenGraph(data) sets Open Graph/Twitter meta tags
• Utilities (optional): resolveOptions, buildShareText

Quick start

import React from 'react';
import { createRoot } from 'react-dom/client';
import {
  SocialShareWrapper,
  useSocialShareContext,
  useOpenGraph,
} from '@sonardigital/social-share';

function Page() {
  // Optional: set Open Graph and Twitter meta tags
  useOpenGraph({
    title: 'Adopt a lovely pet',
    description: 'Find your new best friend today',
    image: 'https://example.com/og.jpg',
    url: 'https://example.com/pets/123',
    siteName: 'Pet Adoption Platform',
  });

  const { shareToFacebook, shareToWhatsApp } = useSocialShareContext();

  return (
    <div>
      <button onClick={() => shareToFacebook({})}>Share on Facebook</button>
      <button onClick={() => shareToWhatsApp({ title: 'Check this pet!' })}>
        Share on WhatsApp
      </button>
    </div>
  );
}

createRoot(document.getElementById('root')!).render(
  <SocialShareWrapper
    defaultTitle="Pet Adoption Platform"
    defaultDescription="Discover pets near you"
    defaultHashtags={["adopt", "pets"]}
  >
    <Page />
  </SocialShareWrapper>
);

API

• SocialShareWrapper(props)

  • defaultUrl?: string — fallback is window.location.href
  • defaultTitle?: string — fallback is document.title
  • defaultDescription?: string
  • defaultImage?: string
  • defaultHashtags?: string[]
  • methods?: return value of useSocialShare to override/inject your own methods

• useSocialShare(props?) → SocialShareMethods

  • Same props as SocialShareWrapper (without methods).
  • Returns:
    • shareToFacebook(options)
    • shareToWhatsApp(options)
    • shareToTelegram(options)
    • shareToTikTok(options) — copies content to clipboard and opens TikTok
    • Optional extras:
      • shareToWhatsAppStory?(options) — uses Web Share API if available; clipboard fallback
      • shareToInstagramStory?(options) — clipboard helper for story text
      • shareToLinkedIn?(options)

• useSocialShareContext() → SocialShareMethods

  • Reads the share methods from context. Throws if used outside SocialShareWrapper.

• useOpenGraph(data: OpenGraphData)

  • Sets <meta property="og:*"> and Twitter <meta name="twitter:*"> tags, and updates document.title.

Utilities (optional)

• resolveOptions(defaults, options) → ResolvedSocialShareOptions

  • Merges per-call options with hook/provider defaults and available Open Graph meta tags on the page.
  • Useful if you build your own share flows.

• buildShareText({ title?, description?, hashtags? }) → string

  • Builds a shareable text block combining title, description, and #hashtags.

Types

// Share inputs
export interface SocialShareOptions {
  url?: string;
  title?: string;
  description?: string;
  image?: string;
  hashtags?: string[];
}

export interface UseSocialShareProps {
  defaultUrl?: string;
  defaultTitle?: string;
  defaultDescription?: string;
  defaultImage?: string;
  defaultHashtags?: string[];
}

export interface OpenGraphData {
  title?: string;
  description?: string;
  image?: string;
  url?: string;
  type?: string;
  siteName?: string;
}

All types and utilities are exported from the package root:

import type { SocialShareOptions, UseSocialShareProps, OpenGraphData } from '@sonardigital/social-share';
import { resolveOptions, buildShareText } from '@sonardigital/social-share';

Examples

Override defaults per call

const { shareToTelegram } = useSocialShareContext();
shareToTelegram({
  url: 'https://example.com/pets/123',
  title: 'Meet Luna',
  description: '2‑year‑old playful cat',
  hashtags: ['adopt', 'cats']
});

Use without provider

import { useSocialShare } from '@sonardigital/social-share';

function StandaloneButton() {
  const { shareToLinkedIn } = useSocialShare({ defaultTitle: 'Company blog' });
  return <button onClick={() => shareToLinkedIn({ url: 'https://example.com/blog' })}>Share</button>;
}

Open Graph helper only

import { useOpenGraph } from '@sonardigital/social-share';

function HeadTags() {
  useOpenGraph({ title: 'Article', description: 'Great read', image: 'https://example.com/og.jpg' });
  return null;
}

Utilities only

import { resolveOptions, buildShareText } from '@sonardigital/social-share';

const defaults = {
  defaultUrl: window.location.href,
  defaultTitle: document.title,
  defaultDescription: '',
  defaultImage: '',
  defaultHashtags: ['adopt', 'pets']
};

const resolved = resolveOptions(defaults, { title: 'Meet Luna', url: 'https://example.com/pets/123' });
const text = buildShareText({ title: resolved.title, description: resolved.description, hashtags: resolved.hashtags });

Notes & limitations

• Designed for browsers. Uses window, document, navigator.clipboard, window.open.
• Popup blockers may affect new window behavior on some platforms.
• Instagram and TikTok do not offer direct web share APIs; utilities assist by copying text to clipboard and opening their pages.
• Some share endpoints (e.g., Facebook/LinkedIn) may change over time.

License

ISC