RavenMux

One-Stop Social Share SDK with compound components. Headless core with optional React UI layer.

Installation

# Using Bun (recommended for development)
bun install ravenmux

# Using npm
npm install ravenmux

# Using yarn
yarn add ravenmux

# Using pnpm
pnpm add ravenmux

Usage

Headless API (Core)

Use the core module for programmatic share URL generation:

import { share } from 'ravenmux/core';

// Generate an X share URL
const xUrl = share('x', {
  url: 'https://example.com',
  text: 'Check this out!'
});
// Returns: https://x.com/intent/post?url=https%3A%2F%2Fexample.com&text=Check%20this%20out%21

// Generate a LinkedIn share URL
const linkedinUrl = share('linkedin', {
  url: 'https://example.com',
  text: 'Great article about development'
});

Global Theme Setup (Recommended)

Just like Tailwind, you can set a global theme for all RavenMux components using the RavenMuxProvider:

import { RavenMuxProvider, SocialLink, ShareButton } from "ravenmux/react";

function App() {
  return (
    <RavenMuxProvider theme="dark">
      {/* All RavenMux components automatically use the dark theme */}
      <Header />
      <Footer />
    </RavenMuxProvider>
  );
}

function Footer() {
  return (
    <footer>
      <nav className="flex gap-4">
        {/* No need to pass theme prop - uses global dark theme */}
        <SocialLink provider="x" username="ravenmux" variant="icon" />
        <SocialLink provider="github" username="ravenmux" variant="icon" />
        <SocialLink provider="linkedin" username="ravenmux" variant="icon" />
      </nav>
    </footer>
  );
}

Global Theme Props

RavenMuxProvider

• theme: 'light' | 'dark' | Theme - Global theme for all components
• className: string - Global Tailwind classes applied to all buttons
• icons: Partial<Record<SocialLinkProvider, ReactNode | string>> - Global icon overrides for link buttons (e.g. brand asset URLs or React nodes)
• shareIcons: Partial<Record<string, ReactNode | string>> - Global icon overrides for share buttons
• children: React nodes

// Apply global Tailwind classes to all buttons
<RavenMuxProvider 
  theme="light"
  className="rounded-lg shadow-md hover:shadow-lg transition-shadow"
>
  <YourApp />
</RavenMuxProvider>

// Use brand assets for all X and LinkedIn links
<RavenMuxProvider icons={{ x: '/brand/x.svg', linkedin: '/brand/linkedin.svg' }}>
  <SocialLink provider="x" username="ravenmux" variant="icon" />
</RavenMuxProvider>

Local Override

You can still override the global theme on individual components:

<RavenMuxProvider theme="light">
  <SocialLink provider="x" username="user1" variant="icon" /> {/* Light theme */}
  <SocialLink 
    provider="github" 
    username="user2" 
    variant="icon" 
    theme="dark"  {/* Override: dark theme */}
  />
</RavenMuxProvider>

React Components (UI)

Compound Components (Maximum Flexibility)

import { Share } from 'ravenmux/react';

// Icon-only share button
<Share provider="x" url="https://example.com" theme="dark">
  <Share.Button variant="icon" />
</Share>

// Button with label
<Share provider="linkedin" url="https://example.com" theme="light">
  <Share.Button variant="button" />
  <Share.Label>Share on LinkedIn</Share.Label>
</Share>

// Maximum flexibility - compose your own
<Share provider="x" url="https://example.com" text="Check this!">
  <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
    <Share.Icon />
    <Share.Label>Post to X</Share.Label>
  </div>
</Share>

Simple ShareButton (Convenience)

import { ShareButton } from 'ravenmux/react';

// Icon-only
<ShareButton
  provider="x"
  url="https://example.com"
  variant="icon"
  theme="dark"
/>

// Button with label
<ShareButton
  provider="linkedin"
  url="https://example.com"
  text="Check this article"
  variant="button"
  label="Share on LinkedIn"
  theme="light"
/>

Custom Themes

import { ShareButton } from 'ravenmux/react';
import type { Theme } from 'ravenmux/react';

const customTheme: Theme = {
  bg: '#ff6b6b',
  fg: '#ffffff',
  border: '#ee5a5a',
  primary: '#ff6b6b',
  hoverBg: '#ee5a5a',
  activeBg: '#dd4949',
  disabledBg: '#ffb4b4',
  disabledFg: '#ffffff',
  borderRadius: '8px',
  fontFamily: 'Inter, sans-serif',
  fontSize: '16px',
  fontWeight: 600,
  padding: '12px 24px',
  iconSize: '24px',
};

<ShareButton
  provider="x"
  url="https://example.com"
  theme={customTheme}
/>

Brand asset icons

You can use your own icon images or SVG (e.g. official brand assets) instead of the built-in icons.

Per-instance: pass iconSrc (image/SVG URL) or icon (React node) to any link or share component.

// Image or SVG URL (common for brand assets)
<SocialLink provider="x" username="ravenmux" variant="icon" iconSrc="/assets/x-logo.svg" />

// Custom React node
<SocialLink provider="x" username="ravenmux" variant="icon" icon={<img src="/x.png" alt="" />} />

// Share button with custom icon
<ShareButton provider="x" url="https://example.com" variant="icon" iconSrc="/brand/x.svg" />

Global: set icons or shareIcons on RavenMuxProvider so all links/shares for that provider use the same asset. Per-instance icon/iconSrc overrides the global value.

<RavenMuxProvider icons={{ x: '/brand/x.svg', linkedin: '/brand/linkedin.svg' }}>
  <SocialLink provider="x" username="ravenmux" variant="icon" />
</RavenMuxProvider>

API Reference

Core

share(provider, options)

Generates a share URL for the specified provider.

Parameters:

• provider: 'x' | 'linkedin' | 'whatsapp' | 'email' | 'pinterest' | 'facebook' | 'copy' (also accepts 'twitter' for backward compatibility)
• options: { url: string; text?: string }

Returns: string - The full share URL

Throws: RavenMuxError - If provider is unknown or options are invalid

React Components

<Share.Root />

Context provider for share state.

Props:

• provider (required): Provider ID ('x', 'twitter', 'linkedin', 'whatsapp', 'email', 'pinterest', 'facebook', 'copy')
• url (required): URL to share
• text: Optional text to share
• theme: 'light' | 'dark' | Theme
• icon: Custom icon (React node). Overrides default SVG and global shareIcons when set.
• iconSrc: Custom icon image/SVG URL. Overrides default SVG and global shareIcons when set.

<Share.Button />

Clickable button that triggers sharing.

Props:

• variant: 'icon' | 'button' (default: 'button')
• className: Additional CSS classes (Tailwind classes automatically take precedence)
• style: Inline styles
• target: Target window name
• disabled: Disable the button

<Share.Icon />

Provider-specific icon.

Props:

• className: Additional CSS classes
• size: Icon size (defaults to theme)

<Share.Label />

Label text for the share action.

Props:

• children: Label content (defaults to "Share on {Provider}")
• className: Additional CSS classes (Tailwind classes automatically take precedence)
• style: Inline styles

<ShareButton />

Convenience wrapper combining Share.Root and Share.Button.

Props: All Share.Root props plus:

• variant: 'icon' | 'button'
• label: Label text (for button variant)
• icon: Custom icon (React node). Overrides default SVG and global shareIcons when set.
• iconSrc: Custom icon image/SVG URL. Overrides default SVG and global shareIcons when set.
• className: Additional CSS classes (Tailwind classes automatically take precedence)

LinkButton Components (Profile Links)

<LinkButton.Root />

Context provider for social profile link state.

Props:

• provider (required): Social platform ('x', 'linkedin', 'github', 'instagram', 'facebook', 'youtube', 'whatsapp')
• username (required): Username/handle
• theme: 'light' | 'dark' | Theme
• icon: Custom icon (React node). Overrides default SVG and global icons when set.
• iconSrc: Custom icon image/SVG URL. Overrides default SVG and global icons when set.

<LinkButton.Button />

Clickable button that opens the profile URL.

Props:

• variant: 'icon' | 'button' (default: 'button')
• className: Additional CSS classes (Tailwind classes automatically take precedence)
• style: Inline styles
• target: Target window name (default: '_blank')
• disabled: Disable the button

<LinkButton.Icon />

Social platform icon.

Props:

• className: Additional CSS classes (Tailwind classes automatically take precedence)
• size: Icon size
• color: Custom icon color

<LinkButton.Label />

Label text for the link.

Props:

• children: Label content (defaults to "Follow on {Provider}")
• className: Additional CSS classes (Tailwind classes automatically take precedence)
• style: Inline styles

<SocialLink />

Convenience wrapper combining LinkButton.Root and LinkButton.Button.

Props:

• provider (required): Social platform
• username (required): Username/handle
• variant: 'icon' | 'button'
• label: Label text (for button variant)
• icon: Custom icon (React node). Overrides default SVG and global icons when set.
• iconSrc: Custom icon image/SVG URL. Overrides default SVG and global icons when set.
• className: Additional CSS classes (Tailwind classes automatically take precedence)

Error Handling

import { share, RavenMuxError } from 'ravenmux/core';

try {
  const url = share('unknown-provider', { url: 'https://example.com' });
} catch (error) {
  if (error instanceof RavenMuxError) {
    console.log(error.code); // 'UNKNOWN_PROVIDER'
    console.log(error.message);
  }
}

Supported Providers

Share Providers

• X (formerly Twitter) - Share posts with text, hashtags, and related accounts
• LinkedIn - Share posts with title, summary, and source
• WhatsApp - Share via wa.me with a single text param (url + optional text); optional phone to open chat with a number
• Email - Share via mailto: (subject and body); opens default mail client
• Pinterest - Share via Pin Create URL (url, optional media image URL, description or text)
• Facebook - Share via Facebook sharer (u param); preview uses the page’s Open Graph tags
• Copy Link - Copies the URL to the clipboard (no new window)

Note: The provider ID 'twitter' is still supported for backward compatibility and maps to X.

Social Link Providers

• X - Link to X profiles (x.com/username)
• LinkedIn - Link to LinkedIn profiles (linkedin.com/in/username)
• GitHub - Link to GitHub profiles (github.com/username)
• Instagram - Link to Instagram profiles (instagram.com/username)
• Facebook - Link to Facebook profiles (facebook.com/username)
• YouTube - Link to YouTube channels (youtube.com/username)
• WhatsApp - Link to chat (wa.me/<number>); use phone number as username (e.g. 15551234567)

Architecture

RavenMux is built with a two-layer architecture:

┌─────────────────────────────────────┐
│  UI Layer (Optional)                │
│  - React compound components        │
│  - Theme tokens                     │
│  - Inline SVG icons                 │
│  - Tailwind CSS support             │
├─────────────────────────────────────┤
│  Core Layer (Headless)              │
│  - share() function                 │
│  - Social profile URL generator     │
│  - Provider registry                │
│  - Validation & encoding            │
│  - Typed errors                     │
└─────────────────────────────────────┘

The UI layer imports only from core, ensuring no React code in the headless API. Components support both theme-based styling and Tailwind CSS customization.

Tailwind CSS Support

RavenMux components fully support Tailwind CSS for styling. When you provide a className prop, Tailwind classes automatically take precedence over default styles.

Automatic Precedence

When you provide Tailwind classes via the className prop, the component automatically detects this and skips applying conflicting inline styles (like width, height, padding, backgroundColor, etc.). This means your Tailwind classes work seamlessly without any extra configuration!

import { ShareButton, SocialLink } from "ravenmux/react";

// Tailwind classes work automatically - no extra props needed!
<SocialLink
  provider="x"
  username="ravenmux"
  variant="icon"
  className="bg-blue-400 hover:bg-blue-500 p-3 rounded-full transition-colors"
/>

// Share button with full Tailwind styling
<ShareButton
  provider="linkedin"
  url="https://example.com"
  variant="button"
  label="Share"
  className="flex items-center gap-2 bg-blue-600 text-white px-4 py-2 rounded-lg hover:bg-blue-700 transition-colors"
/>

How It Works

• With className: Tailwind classes take full control of styling
• Without className: Default theme styles are applied automatically
• Mix both: Use theme prop for base styling + Tailwind for enhancements

Examples

// Icon buttons with Tailwind
<SocialLink 
  provider="github"
  username="octocat"
  variant="icon"
  className="w-10 h-10 flex items-center justify-center bg-gray-800 text-white rounded-full hover:bg-gray-900 transition-colors"
/>

// Gradient background
<SocialLink 
  provider="instagram"
  username="natgeo"
  variant="icon"
  className="w-12 h-12 flex items-center justify-center rounded-full bg-lineaer-to-r from-purple-500 to-pink-500 text-white hover:scale-110 transition-transform"
/>

// With theme + Tailwind effects
<ShareButton
  provider="x"
  url="https://example.com"
  theme="dark"
  variant="icon"
  className="hover:scale-110 transition-transform"
/>

Compound Components with Tailwind

import { Share, LinkButton } from "ravenmux/react";

// Share component with Tailwind
<Share provider="linkedin" url="https://example.com">
  <Share.Button className="flex items-center gap-2 border-2 border-blue-600 text-blue-600 px-4 py-2 rounded hover:bg-blue-50 transition-colors">
    <Share.Icon className="w-5 h-5" />
    <Share.Label className="font-semibold">Share</Share.Label>
  </Share.Button>
</Share>

// LinkButton with Tailwind
<LinkButton.Root provider="x" username="yourbusiness">
  <LinkButton.Button className="group flex items-center gap-2 text-gray-600 hover:text-black transition-colors">
    <LinkButton.Icon className="w-6 h-6 group-hover:scale-110 transition-transform" />
    <LinkButton.Label className="text-sm font-medium">Follow us</LinkButton.Label>
  </LinkButton.Button>
</LinkButton.Root>

Tailwind Customization Examples

// Different sizes
<ShareButton
  provider="x"
  url="https://example.com"
  className="text-sm px-3 py-1"  // Small
/>

<ShareButton
  provider="x"
  url="https://example.com"
  className="text-lg px-6 py-3"  // Large
/>

// With animations
<SocialLink
  provider="github"
  username="yourusername"
  className="hover:rotate-12 transition-transform duration-300"
/>

// Grid layout for multiple social links
<div className="flex gap-4">
  <SocialLink provider="x" username="business" className="p-2 hover:bg-gray-100 rounded" />
  <SocialLink provider="linkedin" username="company" className="p-2 hover:bg-blue-50 rounded" />
  <SocialLink provider="github" username="org" className="p-2 hover:bg-gray-100 rounded" />
  <SocialLink provider="instagram" username="brand" className="p-2 hover:bg-pink-50 rounded" />
</div>

Requirements

• React 18+ (peer dependency)
• TypeScript 5+ (for development)
• Tailwind CSS (optional, for styling)

License

MIT