streamlit-surfside-labs-ui 0.2.0

Animated background effects for Streamlit applications

🎨 Streamlit Effects

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

✨ 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:

pip install streamlit-effects

Or with uv (recommended):

uv pip install streamlit-effects

🚀 Quick Start

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.

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.

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.

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.

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.

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:

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

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:

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:

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:

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:

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

# 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 file for details.

🙏 Acknowledgments

• Built with Streamlit
• Inspired by the amazing Streamlit community
• Canvas animations powered by HTML5 Canvas API

📧 Contact

• GitHub: yourusername/streamlit-effects
• Issues: Report a bug or request a feature
• Discussions: Ask questions or share ideas

⭐ 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