RailsTipjar

A reusable, customizable tip jar feature for Rails applications. Add a beautiful tip jar to any Rails app with just a few lines of code! Works with any payment provider - Stripe, PayPal, Buy Me a Coffee, Ko-fi, or any custom payment link.

Hat example: |Standard|Hovered| |--------|-------| | Screenshot 2025-09-12 at 10 22 51 AM | Screenshot 2025-09-12 at 10 20 50 AM |

Features

🎨 Customizable floating button with multiple icon options (coffee, heart, star, dollar, jar)
🎨 Custom color theming with configurable background and text colors
💫 Optional pulsing animation effect
💳 Works with any payment provider (Stripe, PayPal, Ko-fi, Buy Me a Coffee, etc.)
📱 Fully responsive design with inline styles (no CSS dependencies)
🎯 Multiple positioning options (bottom-right, bottom-left, top-right, top-left)
🌙 Light/Dark theme support for modal
⚡ Stimulus.js powered interactions
🔧 Zero configuration to get started
🚀 Simple mode: Direct link without modal
✨ Fully self-contained (v0.2.0+)

Why Use Payment Links?

No payment code in your Rails apps
No PCI compliance concerns - handled by your payment provider
Multiple provider options - use Stripe, PayPal, Ko-fi, Buy Me a Coffee, or any service
International support - most providers support multiple currencies
Professional checkout experience managed by the provider
Automatic receipts and tax handling by the payment provider

Installation

Add this gem to your Rails application's Gemfile:

# From RubyGems
gem 'rails_tipjar'

Then execute:

```bash
bundle install

Quick Start

1. Create Payment Links

Choose your preferred payment provider and create payment links:

Popular Options:

Stripe: dashboard.stripe.com/payment-links
PayPal: paypal.com/paypalme
Ko-fi: ko-fi.com
Buy Me a Coffee: buymeacoffee.com
GitHub Sponsors: github.com/sponsors

Create links for different amounts or use a single link that accepts custom amounts.

2. Add to Your Views

No configuration file needed! Simply use the helper in your views with all options:

Simple Button (Direct Link)

Add directly to any view:

<!-- Basic usage with default jar icon -->
<%= tip_jar payment_link: 'https://your.payment.link' %>

<!-- With all customization options -->
<%= tip_jar payment_link: 'https://your.payment.link',
            message: 'Support This Project',     # Text shown on hover
            icon: :heart,                        # :coffee, :heart, :star, :dollar, :jar, :hat, or custom SVG
            position: :bottom_right,              # :bottom_right, :bottom_left, :top_right, :top_left
            color: '#8b5cf6',                    # Button background color
            text_color: '#ffffff',               # Button text color
            pulse: true,                         # Enable pulsing animation
            z_index: 1000,                       # Stack order
            class: 'my-custom-class' %>          # Additional CSS classes

<!-- Modal with multiple payment amounts -->
<%= tip_jar payment_links: {
              small: 'https://your-provider.com/tip-5',
              medium: 'https://your-provider.com/tip-10',
              large: 'https://your-provider.com/tip-25'
            },
            modal_title: 'Support my work',
            modal_description: 'Your support helps me continue creating.',
            custom_amounts: [
              { amount: 5, label: '$5', default: false },
              { amount: 10, label: '$10', default: true },
              { amount: 25, label: '$25', default: false }
            ],
            theme: :light %>                     # :light, :dark, :auto

<!-- Force modal mode with single link -->
<%= tip_jar payment_link: 'https://your.payment.link',
            use_modal: true,
            modal_title: 'Choose your support amount' %>

In Layouts

Add to app/views/layouts/application.html.erb:

<!DOCTYPE html>
<html>
  <head>
    <!-- your head content -->
  </head>
  <body>
    <%= yield %>

    <!-- Add floating tip jar button -->
    <%= tip_jar payment_link: 'https://your.payment.link',
                position: :bottom_right %>
  </body>
</html>

That's it! You now have a working tip jar on your site.

Common Options

Option	Description	Default	Values
`payment_link`	Single payment URL for simple mode	-	URL string
`payment_links`	Hash of payment URLs for modal mode	-	Hash with keys like `:small`, `:medium`, `:large`
`message` / `button_text`	Text shown on button (on hover)	`"Tip Jar"`	String
`icon`	Button icon	`:jar`	`:coffee`, `:heart`, `:star`, `:dollar`, `:jar`, `:hat`, or custom SVG
`position`	Button position on screen	`:bottom_right`	`:bottom_right`, `:bottom_left`, `:top_right`, `:top_left`
`color`	Button background color	`"#3b82f6"`	Hex color string
`text_color`	Button text color	`"#ffffff"`	Hex color string
`pulse`	Enable pulsing animation	`false`	`true` / `false`
`z_index`	CSS z-index for stacking	`1000`	Integer
`class`	Additional CSS classes	`""`	String
`use_modal`	Force modal mode	`false`	`true` / `false`

Option	Description	Default
`modal_title`	Modal header text	`"Support my work"`
`modal_description`	Modal description text	`"Your support helps..."`
`theme`	Modal color theme	`:light`
`custom_amounts`	Array of amount options	See example below

Custom Amounts Example

custom_amounts: [
  { amount: 5, label: "$5", default: false },
  { amount: 10, label: "$10", default: true },  # This will be pre-selected
  { amount: 25, label: "$25", default: false },
  { amount: 50, label: "$50", default: false }
]

## Styling

As of v0.2.0, the gem is fully self-contained with inline styles - no external CSS required! The button works out of the box without any app-side styling.

### Customization Options

1. **Via Helper Options** (Recommended):
```erb
<%= tip_jar payment_link: 'https://your.link',
            color: '#10b981',       # Green background
            text_color: '#000000',  # Black text
            pulse: true,            # Enable pulsing animation
            class: 'custom' %>      # Add custom CSS classes

Via CSS Classes (for modal mode): ```css /* Button */ .tipjar-button { } .tipjar-button-icon { } .tipjar-button-text { }

/* Modal */ .tipjar-modal { } .tipjar-modal-content { } .tipjar-modal-header { } .tipjar-amount-button { } .tipjar-amount-active { } .tipjar-submit-button { }


## Development

After checking out the repo:

```bash
cd rails_tipjar
bundle install

To test in a Rails app, add to your Gemfile:

gem 'rails_tipjar', path: '../path/to/rails_tipjar'

Icon Options

The gem includes 6 built-in icons:

:jar - Tip jar with animated coin (default)
:coffee - Coffee cup with steam animation
:heart - Heart shape
:star - Star
:dollar - Dollar sign in circle
:hat - Upside-down busker hat with animated coin drop

You can also provide a custom SVG string for complete customization.

Version History

v1.0.4 - Fixed Safari animation rendering issue with black backgrounds (added fill to animated coins)
v1.0.3 - Removed deprecated features: analytics, backwards compatibility helpers (tipjar_button, tipjar_link, tipjar_modal), and generators
v1.0.2 - Added new :hat icon option (busker-style upside-down hat with animated coin drop)
v1.0.1 - Changed default button text to "Tip Jar" and default icon to jar
v1.0.0 - Stable release with all configuration in view helper options (no initializer needed!)
v0.3.0 - Made payment provider agnostic (works with any payment link service)
v0.2.2 - Added color customization and pulse animation control
v0.2.1 - Fixed button circular shape when icon only displayed
v0.2.0 - Made gem fully self-contained with inline styles
v0.1.0 - Initial release

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/justinpaulson/rails_tipjar.

License

The gem is available as open source under the terms of the MIT License.