@afixt/shareable

A lightweight, accessible, and customizable social sharing widget for modern web applications.

✨ Features

• 🪶 Lightweight: < 10KB gzipped with zero dependencies
• ♿ Accessible: WCAG 2.2 Level AA compliant with full keyboard support
• 🎨 Customizable: Multiple styles, themes, and layouts
• 🔒 Privacy-First: No tracking, cookies, or third-party API calls
• ⚡ Performant: < 100ms script execution on page load
• 🌐 Framework Support: Works with React, Vue, Angular, or vanilla JS

📦 Installation

NPM

npm install @afixt/shareable

CDN

<script src="https://cdn.shareablejs.com/shareable.min.js"></script>

Framework-Specific Packages

npm install react-shareable    # React wrapper
npm install vue-shareable      # Vue wrapper
npm install angular-shareable  # Angular wrapper

🚀 Quick Start

Vanilla JavaScript

<!-- Using data attributes -->
<div class="shareable"
     data-networks="facebook,twitter,linkedin"
     data-title="Check out this awesome content!">
</div>

<!-- Using JavaScript API -->
<div id="share-buttons"></div>
<script>
  Shareable.init({
    container: '#share-buttons',
    networks: ['facebook', 'twitter', 'linkedin', 'email'],
    style: 'icon-text',
    theme: 'auto'
  });
</script>

React

import { ShareableWidget } from 'react-shareable';

function App() {
  return (
    <ShareableWidget
      networks={['facebook', 'twitter', 'linkedin']}
      title="Check out this content!"
      onShare={(event) => console.log('Shared on:', event.network)}
    />
  );
}

Vue

<template>
  <shareable-widget
    :networks="['facebook', 'twitter', 'linkedin']"
    :title="articleTitle"
    @share="handleShare"
  />
</template>

<script>
import { ShareableWidget } from 'vue-shareable';
export default {
  components: { ShareableWidget }
};
</script>

Angular

<shareable-widget
  [networks]="['facebook', 'twitter', 'linkedin']"
  [title]="articleTitle"
  (onShare)="handleShare($event)">
</shareable-widget>

📱 Supported Networks

• Facebook - Share to Facebook feed
• X (Twitter) - Post on X/Twitter
• LinkedIn - Share professional content
• WhatsApp - Direct message sharing
• Telegram - Share via Telegram
• Reddit - Post to Reddit
• Email - Share via email
• Copy Link - Copy URL to clipboard

Plus support for custom networks via the customNetworks API.

⚙️ Configuration Options

Three Ways to Configure

1. HTML Data Attributes

<div class="shareable"
     data-networks="facebook,twitter,linkedin"
     data-style="icon-text"
     data-size="medium"
     data-theme="dark"
     data-title="Amazing Article"
     data-url="https://example.com">
</div>

2. JavaScript API

Shareable.init({
  container: '#share-buttons',
  networks: ['facebook', 'twitter', 'linkedin'],
  style: 'icon-only',      // 'icon-only' | 'text-only' | 'icon-text'
  size: 'medium',           // 'small' | 'medium' | 'large'
  theme: 'dark',            // 'light' | 'dark' | 'auto'
  layout: 'horizontal',     // 'horizontal' | 'vertical' | 'floating-left' | 'floating-right'
  spacing: 12,              // Gap between buttons in pixels
  counters: true,           // Show share counts
  title: 'Check out this article',
  url: 'https://example.com/article',
  hashtags: ['webdev', 'javascript'],
  via: 'username',          // Twitter @mention
  utm: {
    source: 'shareable',
    medium: 'social',
    campaign: 'share'
  }
});

3. JSON Configuration

<script type="application/json" id="shareable-config">
{
  "networks": ["facebook", "twitter", "linkedin"],
  "style": "icon-text",
  "theme": "auto",
  "size": "large"
}
</script>
<div id="share-widget"></div>

🎨 Customization

Styles & Themes

• Styles: icon-only, text-only, icon-text
• Themes: light, dark, auto (follows system preference)
• Sizes: small (24px), medium (32px), large (40px)
• Layouts: horizontal, vertical, floating-left, floating-right

Custom Colors

Shareable.init({
  colors: {
    background: '#ff6b6b',
    foreground: '#ffffff'
  }
});

Custom Networks

Shareable.init({
  networks: ['facebook', 'custom-slack'],
  customNetworks: {
    'custom-slack': {
      name: 'Slack',
      url: 'slack://channel?team={team}&id={channel}',
      icon: '<svg>...</svg>',
      color: '#4A154B'
    }
  }
});

📊 Events & Tracking

// Track share clicks
Shareable.on('click', function(event) {
  console.log('Network:', event.network);
  console.log('URL:', event.url);
  console.log('Title:', event.title);

  // Send to analytics
  gtag('event', 'share', {
    method: event.network,
    content_type: 'article',
    item_id: event.url
  });
});

// Widget loaded event
Shareable.on('load', function(event) {
  console.log('Widget loaded with networks:', event.networks);
});

♿ Accessibility Features

• Full keyboard navigation - Tab, Enter, Space support
• Screen reader support - Descriptive ARIA labels
• Focus indicators - Clear visual focus states
• Touch targets - Minimum 44×44px interactive areas
• Motion preferences - Respects prefers-reduced-motion
• Live regions - Announces actions to screen readers
• WCAG 2.2 AA compliant - Meets all Level AA criteria

📖 API Reference

Methods

// Initialize widget
const widget = Shareable.init(config);

// Update configuration
widget.update({ theme: 'dark', title: 'New Title' });

// Destroy widget
widget.destroy();

// Global event handlers
Shareable.on('click', callback);
Shareable.on('load', callback);
Shareable.off('click', callback);

Configuration Object

| Option | Type | Default | Description | |--------|------|---------|-------------| | container | string | '.shareable' | CSS selector or element | | networks | array | ['facebook', 'twitter', 'linkedin'] | Social networks to display | | style | string | 'icon-only' | Button style | | size | string | 'medium' | Button size | | theme | string | 'light' | Color theme | | layout | string | 'horizontal' | Widget layout | | spacing | number | 8 | Gap between buttons (px) | | counters | boolean | false | Show share counts | | title | string | Auto-detected | Share title | | url | string | Current URL | Share URL | | text | string | Auto-detected | Share description | | hashtags | array | [] | Hashtags for applicable networks | | via | string | null | Twitter username | | utm | object | {} | UTM tracking parameters |

🌐 Browser Support

| Browser | Minimum Version | |---------|-----------------| | Chrome | 90+ | | Firefox | 88+ | | Safari | 14+ | | Edge | 90+ | | iOS Safari | 14+ | | Chrome Android | 90+ |

📚 Examples

View comprehensive examples for all frameworks:

• Live Examples
• Vanilla JavaScript - Pure JS implementation
• React - React hooks and components
• Vue - Vue 3 Composition API
• Angular - Angular directives and services

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

# Clone the repository
git clone https://github.com/afixt/shareable.git

# Install dependencies
npm install

# Run development server
npm run dev

# Run tests
npm test

# Build for production
npm run build

📄 License

MIT © AFixt

🔗 Links

• Documentation
• NPM Package
• GitHub Repository
• Issue Tracker
• Changelog