streamlit-surfside-labs-ui 0.2.0
Animated background effects for Streamlit applications
License: MIT
Requires Python: >=3.8
Keywords: streamlit, components, effects, animations, backgrounds

# 🎨 Streamlit Effects

[![PyPI version](https://badge.fury.io/py/streamlit-effects.svg)](https://pypi.org/project/streamlit-effects/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Animated background effects for Streamlit applications** - Add falling snow, confetti, fireworks, and more to your Streamlit apps with just one line of code!

![Streamlit Effects Demo](https://via.placeholder.com/800x400?text=Demo+GIF+Coming+Soon)

## ✨ Features

- 🎨 **5 Beautiful Effects**: Snow, Confetti, Fireworks, Floating Hearts, Matrix Rain
- 🎯 **Auto-Detection**: Automatically apply seasonal/holiday effects based on current date
- ⚡ **High Performance**: GPU-accelerated CSS animations
- 🎛️ **Fully Customizable**: Control colors, speed, intensity, and more
- 📦 **Zero Dependencies**: Only requires `streamlit>=1.30.0`
- 🚀 **Easy to Use**: One-line function calls
- 💻 **Pure CSS**: Lightweight, no JavaScript bundle

## 📦 Installation

Install via pip:

```bash
pip install streamlit-effects
```

Or with uv (recommended):

```bash
uv pip install streamlit-effects
```

## 🚀 Quick Start

```python
import streamlit as st
from streamlit_effects import snow, confetti

st.title("My Winter App ❄️")

# Add falling snow
snow()

# Celebrate with confetti on button click
if st.button("🎉 Celebrate!"):
    confetti(duration=5)
```

That's it! Your app now has animated background effects.

## 🎨 Available Effects

### ❄️ Snow

Falling snowflakes with customizable intensity, speed, and color.

```python
from streamlit_effects import snow

# Simple usage
snow()

# Custom configuration
snow(
    intensity="heavy",      # "light", "medium", "heavy", "blizzard"
    speed=1.5,              # Speed multiplier (default: 1.0)
    color="#A0D8F1",        # Hex color (default: "#FFFFFF")
    duration=10,            # Auto-stop after 10 seconds
    key="my_snow"           # Unique key for multiple effects
)
```

### 🎉 Confetti

Celebration confetti shower with customizable colors and physics.

```python
from streamlit_effects import confetti

# Simple usage
confetti()

# Custom configuration
confetti(
    duration=5,             # Effect duration in seconds
    particle_count=200,     # Number of confetti pieces
    colors=["#FF0000", "#00FF00", "#0000FF"],  # Custom colors
    velocity=50.0,          # Fall speed
    key="celebration"
)
```

### 🎆 Fireworks

Spectacular fireworks explosions perfect for celebrations.

```python
from streamlit_effects import fireworks

# Simple usage
fireworks()

# Custom configuration
fireworks(
    duration=10,            # Effect duration in seconds
    intensity="heavy",      # "light", "medium", "heavy"
    colors=["#FF0000", "#FFFFFF", "#0000FF"],  # Patriotic colors
    launch_count=5,         # Simultaneous launches
    key="new_year"
)
```

### 💕 Floating Hearts

Romantic floating hearts that rise upward with gentle drift.

```python
from streamlit_effects import floating_hearts

# Simple usage
floating_hearts()

# Custom configuration
floating_hearts(
    intensity="medium",     # "light", "medium", "heavy"
    speed=1.0,              # Float speed multiplier
    colors=["#FF1493", "#FF69B4", "#FFC0CB"],  # Pink shades
    duration=15,            # Auto-stop after 15 seconds
    key="valentines"
)
```

### 🟢 Matrix Rain

Classic Matrix-style digital rain effect with falling code streams.

```python
from streamlit_effects import matrix_rain

# Simple usage
matrix_rain()

# Custom configuration
matrix_rain(
    duration=20,            # Effect duration (None = infinite)
    density="heavy",        # "light" (75), "medium" (150), "heavy" (240) columns
    speed=1.5,              # Fall speed multiplier (1.0 = 30s base)
    color="#00FF00",        # Classic Matrix green
    font_size=16,           # Character size in pixels
    key="enter_matrix"
)
```

**Note**: Matrix effect features 90-character columns with staggered starting positions, smooth fade-in, and English characters only for maximum readability.

## 🎯 Auto-Detection

Automatically apply seasonal and holiday effects based on the current date:

```python
from streamlit_effects import auto_effect

# Automatically detect and apply appropriate effect
effect_name = auto_effect()

if effect_name:
    st.sidebar.info(f"🎨 Today's effect: {effect_name}")
```

**Supported Holidays:**
- 🎆 New Year's Day (Jan 1) → Fireworks
- 💕 Valentine's Day (Feb 14) → Floating Hearts
- 🎆 Independence Day US (Jul 4) → Fireworks
- 🎄 Christmas Season (Dec 20-26) → Snow
- 🎆 New Year's Eve (Dec 31) → Fireworks

**Seasonal Effects:**
- ❄️ Winter (Dec-Feb) → Snow
- 🌸 Spring (Mar-May) → Coming soon
- 🦋 Summer (Jun-Aug) → Coming soon
- 🍂 Fall (Sep-Nov) → Coming soon

## 📚 Complete Example

```python
import streamlit as st
from streamlit_effects import snow, confetti, auto_effect, get_season

st.set_page_config(page_title="My App", page_icon="🎨")

# Sidebar with season info
season = get_season()
st.sidebar.metric("Current Season", season.title())

# Auto-apply seasonal effect
if st.sidebar.checkbox("Enable Seasonal Effects", value=True):
    effect = auto_effect(intensity="medium")
    if effect:
        st.sidebar.success(f"✨ {effect} effect active")

# Main content
st.title("My Awesome Streamlit App 🚀")

# Manual effects
col1, col2, col3 = st.columns(3)

with col1:
    if st.button("❄️ Snow"):
        snow(intensity="heavy", duration=5)

with col2:
    if st.button("🎉 Confetti"):
        confetti(duration=3)

with col3:
    if st.button("🎆 Fireworks"):
        from streamlit_effects import fireworks
        fireworks(duration=8)

# Your app content here
st.write("Welcome to my app!")
```

## 🎛️ Advanced Usage

### Multiple Effects

Use unique `key` parameters to run multiple effects:

```python
from streamlit_effects import snow, confetti

# Both effects will run simultaneously
snow(key="background_snow")
confetti(duration=5, key="celebration_confetti")
```

### Conditional Effects

Apply effects based on app state:

```python
import streamlit as st
from streamlit_effects import fireworks, confetti

# Track user progress
if "tasks_completed" not in st.session_state:
    st.session_state.tasks_completed = 0

if st.button("Complete Task"):
    st.session_state.tasks_completed += 1
    
    # Confetti for each completion
    confetti(duration=2, key=f"task_{st.session_state.tasks_completed}")
    
    # Big fireworks at milestone
    if st.session_state.tasks_completed % 10 == 0:
        fireworks(duration=5, key="milestone")
        st.balloons()
```

### Custom Color Schemes

Create themed effects:

```python
from streamlit_effects import snow, floating_hearts

# Blue winter theme
snow(color="#A0D8F1", intensity="heavy")

# Valentine's theme
floating_hearts(
    colors=["#FF1493", "#FF69B4", "#FFB6C1"],
    intensity="heavy"
)

# Corporate colors
from streamlit_effects import confetti
confetti(
    colors=["#FF6B6B", "#4ECDC4", "#45B7D1"],  # Your brand colors
    particle_count=300
)
```

## 🔧 API Reference

### `snow(intensity, speed, color, particle_count, z_index, duration, key)`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `intensity` | str | `"medium"` | Snow intensity: "light", "medium", "heavy", "blizzard" |
| `speed` | float | `1.0` | Speed multiplier (0.1-3.0) |
| `color` | str | `"#FFFFFF"` | Hex color code |
| `particle_count` | int | None | Override intensity particle count |
| `z_index` | int | `999` | CSS z-index for layering |
| `duration` | int | None | Auto-stop after N seconds (None = infinite) |
| `key` | str | None | Unique component key |

### `confetti(duration, particle_count, colors, spread, origin_x, origin_y, velocity, z_index, key)`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `duration` | int | `5` | Effect duration in seconds |
| `particle_count` | int | `150` | Number of confetti pieces (50-300) |
| `colors` | list | Rainbow | List of hex color codes |
| `spread` | int | `360` | Spread angle in degrees (45-360) |
| `origin_x` | float | `0.5` | Horizontal origin (0.0-1.0) |
| `origin_y` | float | `0.0` | Vertical origin (0.0-1.0) |
| `velocity` | float | `50.0` | Launch velocity (10.0-100.0) |
| `z_index` | int | `999` | CSS z-index for layering |
| `key` | str | None | Unique component key |

### `auto_effect(enable, intensity, **kwargs)`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `enable` | bool | `True` | Enable auto-detection |
| `intensity` | str | `"medium"` | Default intensity for effects |
| `**kwargs` | dict | {} | Additional arguments passed to detected effect |

Returns: `str | None` - Name of effect applied, or None

## 🎓 Examples

Check out the `/examples` directory for complete working examples:

- **`gallery.py`** - Interactive gallery with all effects
- **`quick_test.py`** - Simple test application
- **`seasonal_demo.py`** - Seasonal effects showcase (coming soon)

Run an example:

```bash
streamlit run examples/gallery.py
```

## 🤝 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.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/yourusername/streamlit-effects.git
cd streamlit-effects

# Create virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -e ".[dev]"

# Install frontend dependencies
cd streamlit_effects/frontend
npm install

# Build frontend
npm run build

# Run tests
pytest
```

## 📝 License

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

## 🙏 Acknowledgments

- Built with [Streamlit](https://streamlit.io)
- Inspired by the amazing Streamlit community
- Canvas animations powered by HTML5 Canvas API

## 📧 Contact

- **GitHub**: [yourusername/streamlit-effects](https://github.com/yourusername/streamlit-effects)
- **Issues**: [Report a bug or request a feature](https://github.com/yourusername/streamlit-effects/issues)
- **Discussions**: [Ask questions or share ideas](https://github.com/yourusername/streamlit-effects/discussions)

## ⭐ Show Your Support

If you find this project useful, please consider giving it a star on GitHub! It helps others discover the project.

---

Made with ❤️ by Trent Moore | [Surfside Labs](https://surfsidelabs.com)