streamlit-social-share 0.1.0
Streamlit component that allows you to share your data via the native browser functionality
Requires Python: >=3.7

# 🚀 Streamlit Social Share

[![PyPI version](https://badge.fury.io/py/streamlit-social-share.svg)](https://badge.fury.io/py/streamlit-social-share)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Streamlit](https://img.shields.io/badge/streamlit-1.0+-red.svg)](https://streamlit.io)

A modern, customizable social sharing component for Streamlit applications. Enable users to share your content across multiple social platforms with beautiful, responsive buttons.

![Demo](https://via.placeholder.com/800x400/1f1f1f/ffffff?text=Streamlit+Social+Share+Demo)

## ✨ Features

- **Multiple Built-in Networks**: X (Twitter), LinkedIn, Facebook, WhatsApp, Telegram and more
- **Custom Networks**: Create your own sharing buttons with custom styling and URLs
- **Return Values**: Get feedback on which platform users shared to
- **Easy Integration**: One-line integration with your Streamlit apps
- **Flexible Icons**: Support for emojis, characters, or custom image URLs

## 🎯 Supported Platforms

### 📱 Social Media
- **X (Twitter)** - Share tweets with text and URLs
- **Threads** - Meta's new social platform
- **LinkedIn** - Professional network sharing
- **Facebook** - Share to Facebook timeline
- **Reddit** - Community discussions

### 💬 Messaging
- **Telegram** - Share to Telegram chats
- **WhatsApp** - Share via WhatsApp messages
- **Email** - Opens default email client

## 📦 Installation

```bash
pip install streamlit-social-share
```

## 🚀 Quick Start

```python
import streamlit as st
from streamlit_social_share import streamlit_social_share, create_custom_network

st.title("My Awesome App")

# Basic usage
network = streamlit_social_share(
    text="Check out this amazing Streamlit app!",
    url="https://your-app-url.com",
    networks=["x", "linkedin", "whatsapp", "email"]
)
```

## 📋 API Reference

### `streamlit_social_share()`

| Parameter | Type | Description |
|-----------|------|-------------|
| `text` | `str` | Text to include in the shared message |
| `url` | `str \| None` | URL to share (uses current page if None) |
| `image` | `str \| None` | Image URL to attach (when supported) |
| `networks` | `list[str] \| None` | List of networks to display |
| `key` | `str \| None` | Unique component key |

**Returns:** `str | None` - The network name if shared, None otherwise

## 🎨 Custom Networks

Create your own sharing buttons with the `create_custom_network()` function:

```python
from streamlit_social_share import streamlit_social_share, create_custom_network

# Create custom networks
my_platform = create_custom_network(
    network_id="my_platform",
    name="My Platform", 
    color="#FF6B6B",
    icon="🚀",  # Emoji, character, or image URL
    share_url="https://myplatform.com/share?url={url}&text={text}"
)

dev_to = create_custom_network(
    network_id="dev_to",
    name="Dev.to",
    color="#0A0A0A", 
    icon="https://dev.to/favicon.ico",  # Custom icon URL
    share_url="https://dev.to/new?prefill={text} {url}"
)

# Use custom networks alongside built-in ones
network = streamlit_social_share(
    text="Check out my article!",
    url="https://example.com",
    networks=[my_platform, dev_to, "x", "linkedin"]  # Clean and simple!
)
```

### `create_custom_network()` Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `network_id` | `str` | Unique identifier for the network |
| `name` | `str` | Display name for the button |
| `color` | `str` | Background color (hex code like `#FF6B6B`) |
| `icon` | `str` | Emoji (`🚀`), character, or image URL |
| `share_url` | `str` | URL template with `{text}`, `{url}`, `{image}` placeholders |

**Returns:** `str` - The network_id that can be used in the networks parameter

## 🚀 Example App

A comprehensive example demonstrating all features, network categories, and custom network creation is provided in `example.py`. Run it with:

```sh
streamlit run example.py
```

## 🛠️ Development

### Local Development

```bash
# Clone the repository
git clone https://github.com/lejuliennn/streamlit-social-share.git
cd streamlit-social-share

# Install dependencies
pip install -r requirements.txt

# Run the example
streamlit run example.py
```

### Building

```bash
# Build the package
python setup.py sdist bdist_wheel

# Install locally
pip install -e .
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 📞 Support

- 🐛 Issues: [GitHub Issues](https://github.com/lejuliennn/streamlit-social-share/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/lejuliennn/streamlit-social-share/discussions)